@indiegems/gem-web-sdk 20.1.0 → 21.1.0

package/CHANGELOG.md

@@ -16,6 +16,46 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 21.1.0
+
+Upgrading from 21.0.0. Impact: required.
+
+### Must change
+
+- ShareApi.request now returns a promise instead of nothing. When the Arcade refuses a share, the promise rejects with a ShareRefusal that names the reason and the offending param. Await the call and handle the rejection, for example by telling the player the share could not be sent. With an older Arcade the promise resolves at once, as before. The SDK also refuses, before sending, share params whose keys the Arcade reserves for its own play links, and the error names the key. If your game uses such a name as its own share param, rename it. A current Arcade carries most reserved keys through a share link and returns them unchanged, but an older one still refuses them.
+- PurchaseRefusalCode has a new value, guest_upgrade_required, returned when a web guest tries to spend platform currency directly. Treat it like any other decline: draw no purchase, and do not retry. If you switch over the refusal codes exhaustively, add a case for it or your code will stop compiling.
+
+### Should change
+
+- Spend Gems and Coins through the Arcade's purchase sheet, not through a direct spend on the entity mutations. A web guest's direct spend is now refused. The SDK hands that one refusal to the Arcade as a safety net and rejects your call with the original error straight away, without waiting for an answer or retrying. Move any direct platform-currency spend to the purchase sheet flow. See [the deprecation policy](docs/deprecation-policy.md#4-what-is-deprecated-today).
+
+### Rebuild
+
+- Several types and signatures changed in compatible ways: GemFrame.requestPurchase gained an optional origin argument, GemFrame.requestShare gained an optional requestId argument, the MutationsApi constructor gained an optional hand-off callback, and GemCapability, ParentMessage and PARENT_TO_FRAME gained new capabilities and message kinds for purchase settlement, graphics routes and share results. Recompiling is enough. If you test against your own stand-in for the Arcade, rebuild it against this release and bring it up to the newer parent conformance version.
+
+### New capability
+
+- PurchaseApi.onSettled lets a game hear a purchase that completed after its original call had already been answered, for example one finished through the Arcade after a guest's refused spend. The game is told once the platform confirms the purchase, as a PurchaseSettlement, and the player's data is refreshed. Subscribe to it so you can grant the purchase when it lands. It only fires on an Arcade that supports it.
+- Gem.graphics lets a game ask which renderer to create just before it creates one. The answer says the route to use and whether the device is on the platform's list of devices known to draw wrongly on WebGL. The answer is WebGL everywhere except on a listed device, and there WebGPU only if it hands out an adapter. A listed device with no working WebGPU gets your safe WebGL recipe. The call is time-bounded and never rejects. The list ships built in, and the Arcade can replace it for live games without a rebuild. Call it before creating a renderer and make every canvas follow the answer.
+- A new dev-tools entry point is available for a game's dev-only code, such as a cheat panel, level skipper or debug menu. Importing it from that code marks the build as carrying dev-only code. Builds so marked can be uploaded and played on the dev channel but are refused on the test and release channels. Keep the import behind a build-time switch that is off for test and release builds so the marker is absent from them.
+
+## 21.0.0
+
+Upgrading from 20.1.0. Impact: required.
+
+### May stop
+
+- You do not need to write your own code to count lost WebGL contexts for analytics. Every game now reports each loss automatically, with no code of its own. The SDK only observes the loss, so whether your game restores its context stays your decision, and your own handling keeps working unchanged.
+
+### Rebuild
+
+- The set of platform event names now includes a new member, gem_graphics_context_lost, which the SDK emits when the browser takes away one of the game's WebGL contexts. Recompiling is enough for most games. If your game switches over every platform event name exhaustively, or maps each name to a value, add a case for the new name so it still compiles.
+
+### New capability
+
+- A new in-game Coins icon is available in two sizes, 20 and 32, each at four pixel ratios: 1x, 1.5x, 2x and 3x. It is the Coins coin without the violet rim, so it does not look like the Arcade's own chrome inside a game. Use it wherever your game shows Coins. The wallet icon keeps its violet rim.
+- Two coin piles are now available for showing a Coins reward sized by how much it is: pile 1 for an everyday reward and pile 2 for a bigger one. Each comes in five widths: 128, 256, 384, 512 and 768. They share one frame and baseline, so a row of them climbs from the smaller to the larger. Larger piles are reserved for the Arcade's own shop. The Coins hero art remains the choice when the size of the reward does not matter.
+
 ## 20.1.0
 
 Upgrading from 20.0.0. Impact: required.

package/README.md

@@ -28,6 +28,7 @@ Read them here rather than guessing from the type declarations, which carry sign
 | saving a player's progress | [`docs/saving-player-progress.md`](docs/saving-player-progress.md) |
 | asking the player to sign in | [`docs/player-sign-in.md`](docs/player-sign-in.md) |
 | vibrating the player's device, the iPhone included | [`docs/vibration.md`](docs/vibration.md) |
+| WebGL or WebGPU: which renderer to make on this device | [`docs/graphics-route.md`](docs/graphics-route.md) |
 | leaderboards | [`docs/leaderboards.md`](docs/leaderboards.md) |
 | currencies, items, shops and loot | [`docs/inventory-and-catalogs.md`](docs/inventory-and-catalogs.md), [`docs/game-economy-tutorial.md`](docs/game-economy-tutorial.md), [`docs/trading-and-gifting.md`](docs/trading-and-gifting.md) |
 | Gems, Coins and achievements | [`docs/arcade-economy.md`](docs/arcade-economy.md), [`docs/achievements.md`](docs/achievements.md), [`docs/brand-art.md`](docs/brand-art.md) |

package/dist/conformance.d.ts

@@ -50,7 +50,7 @@ interface ParentConformanceResult {
     readonly ok: boolean;
     readonly message?: string;
 }
-declare const PARENT_CONFORMANCE_VERSION = 4;
+declare const PARENT_CONFORMANCE_VERSION = 6;
 declare const PARENT_CONFORMANCE_CASES: readonly ParentConformanceCase[];
 declare function runParentConformance(factory: ParentFactory, options: ParentConformanceOptions): Promise<readonly ParentConformanceResult[]>;
 export { PARENT_CONFORMANCE_CASES, PARENT_CONFORMANCE_VERSION, type ParentConformanceCase, ParentConformanceError, type ParentConformanceOptions, type ParentConformanceResult, type ParentFactory, type ParentFixture, type ParentState, type ParentUnderTest, runParentConformance };

package/dist/dev-tools.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/function.d.ts

@@ -102,7 +102,7 @@ declare class GemClient {
     private backoff;
 }
 type SessionEndReason = "grant_expiring" | "session_ended" | "navigating" | "kill_switch" | "pagehide";
-type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost";
+type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost" | "gem_graphics_context_lost";
 type AnalyticsValue = string | number;
 interface AnalyticsRejection {
     readonly index: number;
@@ -232,6 +232,13 @@ declare class ChallengesApi {
     constructor(api: GameApi);
     list(options?: ListChallengesOptions): Promise<Challenge[]>;
 }
+interface RefusedPurchase {
+    readonly kind: "item" | "recipe";
+    readonly targetId: string;
+    readonly catalogId?: string;
+    readonly currencySlug: string;
+    readonly quantity: number;
+}
 type CacheParam = string | number | boolean | undefined;
 declare class EntityReadCache {
     private readonly clock;
@@ -471,7 +478,8 @@ declare class MutationsApi {
     private readonly api;
     private readonly entity;
     private readonly cache;
-    constructor(api: GameApi, entity: EntityRef, cache: EntityReadCache);
+    private readonly handOffRefused?;
+    constructor(api: GameApi, entity: EntityRef, cache: EntityReadCache, handOffRefused?: ((refused: RefusedPurchase) => void) | undefined);
     create(operations: readonly InventoryOperation[], options?: OrderOptions): Promise<OrderResult>;
     createMany(orders: ReadonlyArray<readonly InventoryOperation[]>, options?: OrderOptions): Promise<unknown>;
     recipeAvailability(catalogId: string, recipeId: string, signal?: AbortSignal): Promise<RecipeAvailability>;
@@ -1073,4 +1081,4 @@ interface PlayerBoost {
     readonly multipliers: readonly PlayerBoostMultiplier[];
     readonly expiresInDays?: number;
 }
-export { AnalyticsApi, type AnalyticsApiOptions, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Avatar3dFamily, type Base64String, type Boundary, type BucketConfig, type BucketResetInterval, type BytesResponse, CONDITIONAL_HEADERS, type CacheParam, type Challenge, type ChallengeWindow, ChallengesApi, type Character, CharactersApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, type CreateCharacterOptions, CurrenciesApi, type CurrencyBalance, type CurrencyBucket, type CurrencyReadOptions, type CurrencyRow, type DescribeSaveOptions, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EarnAllowanceSignal, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, EntityReadCache, type EntityRef, type EntityScope, type EntityType, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsApiDependencies, type FriendsPage, type FunctionContext, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, type GameApi, type GameOrderSource, type GamePass, GemApiError, GemClient, type GemErrorReason, type GemFunction, GemFunctionError, type GemFunctionIdentity, GemSaveError, type GetLeaderboardOptions, type GetSaveOptions, type GetSettingOptions, type InitiateTransferOptions, InventoryApi, type InventoryItem, type InventoryOperation, type InventorySnapshot, type ItemCategory, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, type ListSavesOptions, type ListTransfersOptions, type LootRoll, MAX_PERIODS_BACK, MutationsApi, type Order, type OrderOptions, type OrderPageOptions, type OrderResult, type OrderSource, OrdersApi, type Page, type PassesApi, type PassesEvent, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlatformPrice, type PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, type PlayerScope, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry, ProfilesApi, type Progression, type ProgressionAchievement, ProgressionsApi, type PurchaseOptions, type PutBytesOptions, type PutSaveOptions, type PutSettingOptions, type RankedRow, type RecipeAvailability, type RecipeChange, type RecipeLock, type RecipeResult, type RecipeUsage, type RecipeUsageList, type RequestOptions, type SavePage, type SaveRecord, SavesApi, type SavesOptions, type SessionEndReason, type Setting, SettingsApi, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SlotInfo, type SnapshotCurrency, type SnapshotItem, type SnapshotOptions, type SnapshotPageOptions, type TokenGrant, type Transfer, type TransferDirection, TransfersApi, type Transport, TransportRefusal, type TransportRequest, type TransportResponse, type VersionedGetOptions, type VersionedResponse, type WornAvatar3d, asPlayerText, createGem, mapIdentity, platformIconUrl, text, toBase64 };
+export { AnalyticsApi, type AnalyticsApiOptions, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Avatar3dFamily, type Base64String, type Boundary, type BucketConfig, type BucketResetInterval, type BytesResponse, CONDITIONAL_HEADERS, type CacheParam, type Challenge, type ChallengeWindow, ChallengesApi, type Character, CharactersApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, type CreateCharacterOptions, CurrenciesApi, type CurrencyBalance, type CurrencyBucket, type CurrencyReadOptions, type CurrencyRow, type DescribeSaveOptions, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EarnAllowanceSignal, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, EntityReadCache, type EntityRef, type EntityScope, type EntityType, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsApiDependencies, type FriendsPage, type FunctionContext, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, type GameApi, type GameOrderSource, type GamePass, GemApiError, GemClient, type GemErrorReason, type GemFunction, GemFunctionError, type GemFunctionIdentity, GemSaveError, type GetLeaderboardOptions, type GetSaveOptions, type GetSettingOptions, type InitiateTransferOptions, InventoryApi, type InventoryItem, type InventoryOperation, type InventorySnapshot, type ItemCategory, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, type ListSavesOptions, type ListTransfersOptions, type LootRoll, MAX_PERIODS_BACK, MutationsApi, type Order, type OrderOptions, type OrderPageOptions, type OrderResult, type OrderSource, OrdersApi, type Page, type PassesApi, type PassesEvent, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlatformPrice, type PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, type PlayerScope, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry, ProfilesApi, type Progression, type ProgressionAchievement, ProgressionsApi, type PurchaseOptions, type PutBytesOptions, type PutSaveOptions, type PutSettingOptions, type RankedRow, type RecipeAvailability, type RecipeChange, type RecipeLock, type RecipeResult, type RecipeUsage, type RecipeUsageList, type RefusedPurchase, type RequestOptions, type SavePage, type SaveRecord, SavesApi, type SavesOptions, type SessionEndReason, type Setting, SettingsApi, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SlotInfo, type SnapshotCurrency, type SnapshotItem, type SnapshotOptions, type SnapshotPageOptions, type TokenGrant, type Transfer, type TransferDirection, TransfersApi, type Transport, TransportRefusal, type TransportRequest, type TransportResponse, type VersionedGetOptions, type VersionedResponse, type WornAvatar3d, asPlayerText, createGem, mapIdentity, platformIconUrl, text, toBase64 };

package/dist/game.d.ts

@@ -621,6 +621,19 @@ type TrackDefinition = {
     "requires_item_id"?: string | null;
     "track_id": string;
 };
+type PurchaseRefusalCode = "unknown_currency" | "currency_not_in_game_payable" | "not_purchasable" | "no_price_in_currency" | "busy" | "cancelled" | "insufficient_funds" | "price_mismatch" | "config_version_stale" | "platform_currency_unavailable" | "not_available" | "recipe_locked" | "already_owned" | "guest_upgrade_required" | "recipe_on_cooldown" | "recipe_max_uses_exceeded" | "item_max_stack_exceeded" | "recipe_costs_unmet" | "quantity_invalid" | "error";
+declare class PurchaseRefusal extends RangeError {
+    readonly code: Extract<PurchaseRefusalCode, "unknown_currency" | "not_purchasable" | "no_price_in_currency" | "quantity_invalid">;
+    readonly retryable: false;
+    constructor(code: Extract<PurchaseRefusalCode, "unknown_currency" | "not_purchasable" | "no_price_in_currency" | "quantity_invalid">, message: string);
+}
+interface RefusedPurchase {
+    readonly kind: "item" | "recipe";
+    readonly targetId: string;
+    readonly catalogId?: string;
+    readonly currencySlug: string;
+    readonly quantity: number;
+}
 type CacheParam = string | number | boolean | undefined;
 declare class EntityReadCache {
     private readonly clock;
@@ -860,7 +873,8 @@ declare class MutationsApi {
     private readonly api;
     private readonly entity;
     private readonly cache;
-    constructor(api: GameApi, entity: EntityRef, cache: EntityReadCache);
+    private readonly handOffRefused?;
+    constructor(api: GameApi, entity: EntityRef, cache: EntityReadCache, handOffRefused?: ((refused: RefusedPurchase) => void) | undefined);
     create(operations: readonly InventoryOperation[], options?: OrderOptions): Promise<OrderResult>;
     createMany(orders: ReadonlyArray<readonly InventoryOperation[]>, options?: OrderOptions): Promise<unknown>;
     recipeAvailability(catalogId: string, recipeId: string, signal?: AbortSignal): Promise<RecipeAvailability>;
@@ -1501,7 +1515,7 @@ declare class FunctionsApi {
 }
 type SessionEndReason = "grant_expiring" | "session_ended" | "navigating" | "kill_switch" | "pagehide";
 type MatchTransport = "dedicated" | "p2p";
-type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost";
+type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost" | "gem_graphics_context_lost";
 declare const PLATFORM_EVENTS: readonly PlatformEventName[];
 type AnalyticsValue = string | number;
 interface AnalyticsRejection {
@@ -1572,6 +1586,22 @@ interface BootTimelineOptions {
 declare function markOnResolve<T>(boot: BootTimeline, name: string, work: Promise<T>, log?: ((message: string) => void) | null): Promise<T>;
 declare function reportOnResolve(boot: BootTimeline, log?: ((message: string) => void) | null): <T>(work: Promise<T>) => Promise<T>;
 declare function createBootTimeline(options?: BootTimelineOptions): BootTimeline;
+type GemGraphicsRoute = "webgpu" | "webgl";
+interface GemPreferredRoute {
+    readonly route: GemGraphicsRoute;
+    readonly listed: boolean;
+}
+interface GemGraphicsRouteEntry {
+    readonly gpu: string;
+    readonly route?: string;
+    readonly host?: string;
+}
+interface PreferredRouteOptions {
+    readonly timeoutMs?: number;
+}
+interface GraphicsApi {
+    preferredRoute(options?: PreferredRouteOptions): Promise<GemPreferredRoute>;
+}
 type DevToolsOpener = "game" | "platform";
 interface GemDevTools {
     open(): Promise<boolean>;
@@ -2276,6 +2306,15 @@ interface GemClusterTarget {
     readonly clusterTargetId: string;
     readonly clusterTargetIds?: string[];
 }
+interface GemGraphicsRoutes {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.graphicsRoutes";
+    readonly entries: {
+        gpu: string;
+        route?: string;
+        host?: string;
+    }[];
+}
 interface GemScreenshotDenied {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.screenshot.denied";
@@ -2333,6 +2372,14 @@ interface GemSettingChange {
     readonly id: string;
     readonly value: boolean | number | string;
 }
+interface GemShareResult {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.shareResult";
+    readonly requestId: string;
+    readonly outcome: "accepted" | "refused";
+    readonly reason?: string;
+    readonly key?: string;
+}
 interface GemPurchaseResult {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.purchaseResult";
@@ -2341,6 +2388,15 @@ interface GemPurchaseResult {
     readonly reason?: string;
     readonly purchaseId?: string;
 }
+interface GemPurchaseSettled {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.purchaseSettled";
+    readonly purchaseKind: "item" | "recipe";
+    readonly targetId: string;
+    readonly catalogId?: string;
+    readonly quantity: number;
+    readonly purchaseId?: string;
+}
 interface GemDeviceSettingsResult {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.deviceSettings.result";
@@ -3004,12 +3060,6 @@ interface GemMatchApi {
     serve(server: GemMatchServerModule, options?: MatchServeOptions): Promise<MatchHosting>;
     connect(options?: MatchConnectOptions): Promise<MatchConnection>;
 }
-type PurchaseRefusalCode = "unknown_currency" | "currency_not_in_game_payable" | "not_purchasable" | "no_price_in_currency" | "busy" | "cancelled" | "insufficient_funds" | "price_mismatch" | "config_version_stale" | "platform_currency_unavailable" | "not_available" | "recipe_locked" | "already_owned" | "recipe_on_cooldown" | "recipe_max_uses_exceeded" | "item_max_stack_exceeded" | "recipe_costs_unmet" | "quantity_invalid" | "error";
-declare class PurchaseRefusal extends RangeError {
-    readonly code: Extract<PurchaseRefusalCode, "unknown_currency" | "not_purchasable" | "no_price_in_currency" | "quantity_invalid">;
-    readonly retryable: false;
-    constructor(code: Extract<PurchaseRefusalCode, "unknown_currency" | "not_purchasable" | "no_price_in_currency" | "quantity_invalid">, message: string);
-}
 interface PurchaseRequest {
     kind: "item" | "recipe";
     targetId: string;
@@ -3026,6 +3076,14 @@ type PurchaseOutcome = {
 };
 interface PurchaseApi {
     request(req: PurchaseRequest): Promise<PurchaseOutcome>;
+    onSettled(listener: (settlement: PurchaseSettlement) => void): () => void;
+}
+interface PurchaseSettlement {
+    readonly kind: "item" | "recipe";
+    readonly targetId: string;
+    readonly catalogId?: string;
+    readonly quantity: number;
+    readonly purchaseId: string;
 }
 interface Avatar3dPurchaseRequest {
     itemId: string;
@@ -3120,8 +3178,11 @@ interface FrameCallbacks {
     onRelayDraining?(msg: GemRelayDraining): void;
     onDedicatedEvent?(msg: GemDedicatedEvent): void;
     onClusterTarget?(msg: GemClusterTarget): void;
+    onGraphicsRoutes?(msg: GemGraphicsRoutes): void;
     onPartyResult?(msg: GemPartyResult): void;
     onPurchaseResult?(msg: GemPurchaseResult): void;
+    onPurchaseSettled?(msg: GemPurchaseSettled): void;
+    onShareResult?(msg: GemShareResult): void;
     onDeviceSettings?(msg: GemDeviceSettings): void;
     onDeviceSettingsResult?(msg: GemDeviceSettingsResult): void;
     onAdResult?(msg: GemAdResult): void;
@@ -3188,7 +3249,7 @@ declare class GemFrame {
     requestShare(params: ReadonlyArray<{
         readonly key: string;
         readonly value: string;
-    }>): boolean;
+    }>, requestId?: string): boolean;
     requestAvatarPicker(tab?: "2d" | "3d"): boolean;
     requestVibrate(pattern: readonly number[]): boolean;
     reportFrameStats(stats: {
@@ -3200,7 +3261,7 @@ declare class GemFrame {
     signal(signal: string, matchId: string, data: Record<string, unknown>): void;
     dedicatedOffer(matchId: string, sdp: string, intent: GemDedicatedOffer["intent"]): void;
     requestParty(requestId: string): boolean;
-    requestPurchase(requestId: string, purchaseKind: "item" | "recipe", targetId: string, currencySlug: string, quantity?: number, catalogId?: string): boolean;
+    requestPurchase(requestId: string, purchaseKind: "item" | "recipe", targetId: string, currencySlug: string, quantity?: number, catalogId?: string, origin?: "sheet" | "direct_refused"): boolean;
     requestAvatar3dPurchase(requestId: string, itemId: string, currencySlug: string): boolean;
     putDeviceSettings(requestId: string, settings: Readonly<Record<string, unknown>>): boolean;
     requestAd(requestId: string, placement: string, format: "interstitial" | "rewarded"): boolean;
@@ -3224,9 +3285,14 @@ declare class GemFrame {
 interface ShareRequest {
     readonly params?: Readonly<Record<string, string>>;
 }
+declare class ShareRefusal extends Error {
+    readonly reason: string;
+    readonly key?: string;
+    constructor(reason: string, key?: string);
+}
 interface ShareApi {
     readonly available: boolean;
-    request(request?: ShareRequest): void;
+    request(request?: ShareRequest): Promise<void>;
 }
 type ArcadeOutcomeKind = "ok" | "declined" | "unavailable";
 interface ArcadeOutcome {
@@ -3600,6 +3666,7 @@ interface Gem {
     readonly gameConfig: GameConfigApi;
     readonly purchases: PurchaseApi;
     readonly deviceSettings: DeviceSettingsApi;
+    readonly graphics: GraphicsApi;
     readonly moments: MomentsApi;
     readonly ads: AdsApi;
     readonly account: AccountApi;
@@ -3662,4 +3729,4 @@ interface ExitAnalytics {
 }
 declare function leaveAndExit(rooms: ExitRooms, bridge: ExitBridge | null, reason?: string, analytics?: ExitAnalytics): Promise<void>;
 declare function createGem(options?: GemOptions): Gem;
-export { ARCADE_EMBEDDERS, AVATAR_RIGS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection, type AnalyticsValue, type AppLinksOutcome, type AppListing, type AppStore, type ArcadeApi, type ArcadeAvailability, type ArcadeOffer, type ArcadeOutcome, type ArcadeOutcomeKind, AuthError, type AuthFailure, type AuthState, type Avatar3dFamily, type Avatar3dOffer, type Avatar3dPrice, type Avatar3dPurchaseRequest, type AvatarRigNode, type AvatarRigs, type Avatars3dApi, type BootMark, type BootTimeline, type BrandingApi, type BrandingAsset, type BrandingAssetOptions, type BrandingCurrency, type BrandingImageOptions, type BrandingList, type BrandingLookup, type BrandingTheme, type BrandingVariant, type Challenge, type ChallengeWindow, ChallengesApi, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, type ControlsApi, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameCard, type GameConfig, type GameMenu, type GameMenuItem, type GamePass, type GameServerLink, type GameSettingsApi, type Gem, GemApiError, type GemAudioChannels, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemControlBox, type GemCorner, type GemDevTools, GemFrame, GemFunctionError, type GemGameChoiceSetting, type GemGameSetting, type GemGameSettingBase, type GemGameSettingChange, type GemGameSettingIcon, type GemGameSettingOption, type GemGameSettingValue, type GemGameSliderSetting, type GemGameToggleSetting, type GemGraphicsQuality, type GemIdentity, type GemInsets, type GemLook, type GemLookBase, type GemLookDelta, type GemLookOptions, type GemLookSpeed, type GemMatchApi, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, type GemRecommendedSettings, type GemReservedArea, GemSaveError, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerLifecycle, type GemTerminationNotice, GemUnframedError, type GemViewport, type GetLeaderboardOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchServeOptions, type MatchTransport, type MenuStyle, type MessageMeta, type MomentKind, type MomentResult, type MomentSignal, type MomentsApi, type MultiTransportSession, PLATFORM_EVENTS, type PassesApi, type PassesEvent, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, type PlayerScope, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RewardCue, type RewardedStatus, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerTokenGrant, type SessionEndReason, type ShareApi, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SimilarGamesOutcome, type SnapshotCurrency, type SnapshotItem, type StoreApi, type StoreOffersOutcome, type StoreSettlement, type TransportAdvert, type TransportKind, TransportRefusal, UNRELIABLE_CHANNEL_LABEL, type VibrationApi, type WalletVisibleOptions, type WornAvatar3d, asPlayerText, createBootTimeline, createGem, experimentSelection, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, text, webTransportAvailable };
+export { ARCADE_EMBEDDERS, AVATAR_RIGS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection, type AnalyticsValue, type AppLinksOutcome, type AppListing, type AppStore, type ArcadeApi, type ArcadeAvailability, type ArcadeOffer, type ArcadeOutcome, type ArcadeOutcomeKind, AuthError, type AuthFailure, type AuthState, type Avatar3dFamily, type Avatar3dOffer, type Avatar3dPrice, type Avatar3dPurchaseRequest, type AvatarRigNode, type AvatarRigs, type Avatars3dApi, type BootMark, type BootTimeline, type BrandingApi, type BrandingAsset, type BrandingAssetOptions, type BrandingCurrency, type BrandingImageOptions, type BrandingList, type BrandingLookup, type BrandingTheme, type BrandingVariant, type Challenge, type ChallengeWindow, ChallengesApi, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, type ControlsApi, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameCard, type GameConfig, type GameMenu, type GameMenuItem, type GamePass, type GameServerLink, type GameSettingsApi, type Gem, GemApiError, type GemAudioChannels, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemControlBox, type GemCorner, type GemDevTools, GemFrame, GemFunctionError, type GemGameChoiceSetting, type GemGameSetting, type GemGameSettingBase, type GemGameSettingChange, type GemGameSettingIcon, type GemGameSettingOption, type GemGameSettingValue, type GemGameSliderSetting, type GemGameToggleSetting, type GemGraphicsQuality, type GemGraphicsRoute, type GemGraphicsRouteEntry, type GemIdentity, type GemInsets, type GemLook, type GemLookBase, type GemLookDelta, type GemLookOptions, type GemLookSpeed, type GemMatchApi, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPreferredRoute, type GemPrefs, type GemRecommendedSettings, type GemReservedArea, GemSaveError, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerLifecycle, type GemTerminationNotice, GemUnframedError, type GemViewport, type GetLeaderboardOptions, type GraphicsApi, type JoinWelcome, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchServeOptions, type MatchTransport, type MenuStyle, type MessageMeta, type MomentKind, type MomentResult, type MomentSignal, type MomentsApi, type MultiTransportSession, PLATFORM_EVENTS, type PassesApi, type PassesEvent, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, type PlayerScope, PlayerText, type PreferredRouteOptions, type ProfileCallOptions, type ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PurchaseSettlement, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RewardCue, type RewardedStatus, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerTokenGrant, type SessionEndReason, type ShareApi, ShareRefusal, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SimilarGamesOutcome, type SnapshotCurrency, type SnapshotItem, type StoreApi, type StoreOffersOutcome, type StoreSettlement, type TransportAdvert, type TransportKind, TransportRefusal, UNRELIABLE_CHANNEL_LABEL, type VibrationApi, type WalletVisibleOptions, type WornAvatar3d, asPlayerText, createBootTimeline, createGem, experimentSelection, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, text, webTransportAvailable };