@indiegems/gem-web-sdk 20.1.0 → 21.1.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v20.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v21.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -1934,6 +1934,12 @@ platform's own refusals arrive as a `GemApiError` whose `code` is its wire
 code — `insufficient_funds`, `recipe_locked`, `price_mismatch`, … Never
 draw a top-up or payment screen of your own for either.
 
+`guest_upgrade_required` means the player is a guest, and the platform
+lets only an account spend. TREAT IT LIKE A DECLINE AND DRAW NOTHING: the
+SDK has already handed the attempt to the arcade, which offers the player
+an account over your game. The call rejects at once rather than waiting
+for them; if they make one and buy, [PurchaseApi.onSettled](#purchaseapi-onsettled) hears it.
+
 | Parameter | Type |
 | --- | --- |
 | `request` | `ConfiguredPurchaseRequest` |
@@ -4012,7 +4018,7 @@ How a match was hosted — the closed set `gem_match_started` and
 ## PlatformEventName
 
 ```ts
-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"
 ```
 
 Every event the SDK emits by itself.
@@ -4030,6 +4036,12 @@ config names them as steps.
 | `gem_boot_ready` | — | `boot_ms` |
 | `gem_match_started` / `gem_match_ended` | `transport` ([MatchTransport](#matchtransport)) | — |
 | `gem_auth_lost` | — | — |
+| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |
+
+`gem_graphics_context_lost` is the browser taking a WebGL context away, or a
+WebGPU device (`route` is then `webgpu`) — usually a GPU driver fault, sized
+per device across every game (`analytics/graphics.ts` lists the dimension
+values).
 
 <a id="platform_events"></a>
 
@@ -7662,21 +7674,26 @@ that can wear them.
 ## GemFrame.requestShare
 
 ```ts
-requestShare(params: readonly { key: string; value: string }[]): boolean
+requestShare(params: readonly { key: string; value: string }[], requestId?: string): boolean
 ```
 
 Ask the arcade to share a link to your game, opened with these launch
 parameters. The arcade builds the link and shows its own share sheet, copy
-or Share panel; nothing comes back, not even whether the player shared.
+or Share panel; nothing about the player comes back, not even whether they
+shared.
 
 Prefer `gem.share.request`, which checks each key and value against the
-arcade's rules and throws on the one that would be refused. This one checks
-only the message's bounds, sends only while connected, and only to an
-arcade that handles share.
+arcade's rules, throws on the one that would be refused, and rejects with
+the arcade's own refusal. This one checks only the message's bounds, sends
+only while connected, and only to an arcade that handles share.
 
-| Parameter | Type |
-| --- | --- |
-| `params` | `readonly { key: string; value: string }[]` |
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `params` | `readonly { key: string; value: string }[]` |  |
+| `requestId` | `string` | Pass one only to an arcade that advertised
+  `shareResult`, which answers it with one `gem.shareResult` through
+  `onShareResult`; any other arcade ignores it. Omit it and nothing
+  answers. |
 
 **Returns.** whether the message left the frame — `false` before the bridge is
   up, for an arcade that does not handle share, and past this frame's own
@@ -11441,6 +11458,25 @@ every account on the device shares it, and it can vanish at any time. A
 game must boot correctly from `null`. Progress belongs in `gem.me.saves`;
 a setting that must follow the player belongs in `gem.me.settings`.
 
+<a id="gem-graphics"></a>
+
+## Gem.graphics
+
+```ts
+readonly graphics: GraphicsApi
+```
+
+Which renderer to make — WebGPU or WebGL — on this device, and whether
+the device is listed as broken on WebGL. Ask
+`gem.graphics.preferredRoute()` just before you make your first renderer.
+
+WebGL is the answer almost everywhere; `webgpu` only on a listed device,
+where WebGPU is available. A listed device that ends up on WebGL draws the
+game's safe WebGL recipe. The list is the platform's, so a new entry
+reaches your live game without a new build.
+
+**Guides.** [graphics-route](../graphics-route.md)
+
 <a id="gem-moments"></a>
 
 ## Gem.moments
@@ -11537,14 +11573,19 @@ the click handler, because `request` throws once it has gone false:
 shareButton.hidden = !gem.share.available;
 shareButton.onclick = () => {
   if (!gem.share.available) return;
-  gem.share.request({ params: { jar: 'JAR-K7P3QXM', n: '2' } });
+  gem.share.request({ params: { jar: 'JAR-K7P3QXM', n: '2' } }).catch((err) => {
+    // A ShareRefusal: err.reason ('reserved_key', 'round_trip', 'too_long')
+    // and err.key say what to fix. Log it; show the player nothing.
+    console.warn(err);
+  });
 };
 ```
 
 - **Call it synchronously from the click** — never from a timer, after an
   `await`, or on a game event.
-- **Never gate progress or a reward on sharing.** You are told nothing
-  back, not even whether the player shared.
+- **Never gate progress or a reward on sharing.** Nothing about the player
+  comes back, not even whether they shared. The promise rejects only when
+  the arcade refused the share, with a [ShareRefusal](#sharerefusal) naming why.
 - **No personal identifiers in `params`.** The link is public.
 - **The share text is the arcade's own**; your game supplies none.
 
@@ -12960,6 +13001,152 @@ whichever transport won, so your game code does not branch.
 
 **Guides.** [dedicated-server-flow](../dedicated-server-flow.md)
 
+<a id="gemgraphicsroute"></a>
+
+## GemGraphicsRoute
+
+```ts
+type GemGraphicsRoute = "webgpu" | "webgl"
+```
+
+Which renderer to make: `webgpu` or `webgl`.
+
+<a id="gempreferredroute"></a>
+
+## GemPreferredRoute
+
+```ts
+interface GemPreferredRoute
+```
+
+What `gem.graphics.preferredRoute()` answers.
+
+<a id="gempreferredroute-route"></a>
+
+## GemPreferredRoute.route
+
+```ts
+readonly route: GemGraphicsRoute
+```
+
+Which renderer to make. `webgpu` only when `listed` is true and the
+browser hands out a WebGPU adapter; `webgl` everywhere else.
+
+<a id="gempreferredroute-listed"></a>
+
+## GemPreferredRoute.listed
+
+```ts
+readonly listed: boolean
+```
+
+Whether the platform lists this device as broken on WebGL. When true and
+`route` is `webgl` (no WebGPU here), or your WebGPU renderer fails to
+start, draw your safe WebGL recipe — for every listed device today, no
+shadow maps — on every WebGL canvas the page makes, menus included.
+
+<a id="gemgraphicsrouteentry"></a>
+
+## GemGraphicsRouteEntry
+
+```ts
+interface GemGraphicsRouteEntry
+```
+
+One device that should draw with WebGPU, as the platform's list names it.
+An absent `route` or `host` matches any.
+
+<a id="gemgraphicsrouteentry-gpu"></a>
+
+## GemGraphicsRouteEntry.gpu
+
+```ts
+readonly gpu: string
+```
+
+The GPU family, e.g. `powervr_d_series`, `adreno`, `mali`.
+
+<a id="gemgraphicsrouteentry-route"></a>
+
+## GemGraphicsRouteEntry.route
+
+```ts
+readonly route?: string
+```
+
+The route WebGL takes there, e.g. `angle_gles` (OpenGL ES),
+`native_gl` (no ANGLE, as the Arcade's Android app reports) or
+`angle_vulkan`. Absent matches any route.
+
+<a id="gemgraphicsrouteentry-host"></a>
+
+## GemGraphicsRouteEntry.host
+
+```ts
+readonly host?: string
+```
+
+`android_webview` (an Android app's WebView, the Arcade app's included) or
+`other`. Absent matches either.
+
+<a id="preferredrouteoptions"></a>
+
+## PreferredRouteOptions
+
+```ts
+interface PreferredRouteOptions
+```
+
+Options for [GraphicsApi.preferredRoute](#graphicsapi-preferredroute).
+
+<a id="preferredrouteoptions-timeoutms"></a>
+
+## PreferredRouteOptions.timeoutMs
+
+```ts
+readonly timeoutMs?: number
+```
+
+The longest the answer may take, in milliseconds. Default 1000, at most
+5000. When it runs out, the answer comes from what is known by then.
+
+<a id="graphicsapi"></a>
+
+## GraphicsApi
+
+```ts
+interface GraphicsApi
+```
+
+Which renderer to make. Reached as `gem.graphics`.
+
+<a id="graphicsapi-preferredroute"></a>
+
+## GraphicsApi.preferredRoute
+
+```ts
+preferredRoute(options?: PreferredRouteOptions): Promise<GemPreferredRoute>
+```
+
+Which renderer to make, and whether this device is listed. Ask once, just
+before you make your first renderer, and follow it for every canvas.
+
+`route` is `webgl` almost everywhere. It is `webgpu` only on a device the
+platform lists as broken on WebGL (today the PowerVR D-Series GPU in the
+Pixel 10, on every route but Vulkan), and only when WebGPU is available
+there. `listed` is true on such a device: when `route` is `webgl` there,
+or making the WebGPU renderer fails, draw your safe WebGL recipe.
+
+Resolves within `timeoutMs` (default 1000 ms) and never rejects; normally
+at once after `gem.awaitBridge()`. The launch key `gemGraphics=webgpu`,
+`gemGraphics=safe` or `gemGraphics=webgl` forces the answer, for testing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `PreferredRouteOptions` | See [PreferredRouteOptions](#preferredrouteoptions). |
+
+**Returns.** `{ route, listed }`.
+
 <a id="gemmatchservermodule"></a>
 
 ## GemMatchServerModule
@@ -15099,6 +15286,102 @@ a Buy button mostly does not write one.
 | --- | --- |
 | `req` | `PurchaseRequest` |
 
+<a id="purchaseapi-onsettled"></a>
+
+## PurchaseApi.onSettled
+
+```ts
+onSettled(listener: (settlement: PurchaseSettlement) => void): () => void
+```
+
+Hear about a purchase of yours that completed AFTER its own call answered
+— returns a function that stops listening.
+
+The case it exists for: a guest's `gem.me.mutations.purchase` is refused
+`guest_upgrade_required` (your call rejects at once, and you show
+nothing), the arcade offers the player an account, and they make one and
+confirm the arcade's sheet a minute later — or after a reload, when the
+call that asked is gone. This is how your game hears that it happened.
+
+THE SDK CONFIRMS IT FIRST. A listener is called only once the platform
+itself, asked with your game's own token, says the purchase was granted;
+a claim it cannot confirm is never reported. The player's inventory is
+re-read either way, so `gem.me.inventory.onChanged` fires too. Treat it
+like an `ok`: grant feedback, then re-read inventory rather than assuming
+what landed.
+
+Hears nothing on an arcade that does not support it (the
+`purchaseSettled` capability), and never for a purchase an `ok` already
+reported.
+
+| Parameter | Type |
+| --- | --- |
+| `listener` | `(settlement: PurchaseSettlement) => void` |
+
+<a id="purchasesettlement"></a>
+
+## PurchaseSettlement
+
+```ts
+interface PurchaseSettlement
+```
+
+A purchase of one of your game's own items or recipes that completed after
+the call that asked for it had answered. What [PurchaseApi.onSettled](#purchaseapi-onsettled)
+hears.
+
+<a id="purchasesettlement-kind"></a>
+
+## PurchaseSettlement.kind
+
+```ts
+readonly kind: "item" | "recipe"
+```
+
+`item` or `recipe`.
+
+<a id="purchasesettlement-targetid"></a>
+
+## PurchaseSettlement.targetId
+
+```ts
+readonly targetId: string
+```
+
+The item-definition or recipe id that was bought.
+
+<a id="purchasesettlement-catalogid"></a>
+
+## PurchaseSettlement.catalogId
+
+```ts
+readonly catalogId?: string
+```
+
+The recipe's catalog; absent for an item.
+
+<a id="purchasesettlement-quantity"></a>
+
+## PurchaseSettlement.quantity
+
+```ts
+readonly quantity: number
+```
+
+How many were bought. Always 1 for a recipe.
+
+<a id="purchasesettlement-purchaseid"></a>
+
+## PurchaseSettlement.purchaseId
+
+```ts
+readonly purchaseId: string
+```
+
+The platform's own id for this purchase, which the SDK confirmed with the
+platform before calling you. A handle for logs and support, as on
+[PurchaseOutcome](#purchaseoutcome)'s `ok`; nothing reads it back.
+
 <a id="avatar3dpurchaserequest"></a>
 
 ## Avatar3dPurchaseRequest
@@ -15136,7 +15419,7 @@ must carry a price in it.
 ## PurchaseRefusalCode
 
 ```ts
-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"
+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"
 ```
 
 Every reason a purchase can be refused, on either purchase path.
@@ -15165,6 +15448,12 @@ Every reason a purchase can be refused, on either purchase path.
 - `already_owned` — the player already owns the 3D avatar
   `gem.avatars3d.purchase` asked for; nothing was charged. Only that call
   answers it.
+- `guest_upgrade_required` — the player is playing as a guest, and the
+  platform lets only an account spend. Nothing was charged. TREAT IT EXACTLY
+  LIKE A DECLINE, AND DRAW NOTHING: the arcade offers the player an account
+  itself, over your game, and a sign-up or "log in to buy" screen of your own
+  would be a second one. A game on `gem.me.mutations.purchase` gets it as a
+  `GemApiError` after the SDK has already handed the attempt to the arcade.
 - `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`,
   `recipe_costs_unmet`, `quantity_invalid` — the recipe or item refused this
   purchase, before any charge.
@@ -15936,6 +16225,44 @@ Your own launch parameters, exactly as they should reach your game when the
 link is opened — the keys you read back from `location.search`. At most 16,
 in the order given. Omit it to share your game with no deep link.
 
+<a id="sharerefusal"></a>
+
+## ShareRefusal
+
+```ts
+class ShareRefusal
+```
+
+The arcade refused a share, and why. `gem.share.request`'s promise rejects
+with it. Fix the params it names: the same share is refused again.
+
+<a id="sharerefusal-reason"></a>
+
+## ShareRefusal.reason
+
+```ts
+readonly reason: string
+```
+
+Why, as a machine code. OPEN-ENDED, so keep a `default` arm:
+
+- `reserved_key` — [ShareRefusal.key](#sharerefusal-key) is a key the arcade keeps for
+  itself and does not carry in a share link.
+- `round_trip` — the link the arcade built does not read back as what you
+  asked for, or [ShareRefusal.key](#sharerefusal-key) is too long to carry.
+- `too_long` — the whole link is over 2 KB. Share fewer or shorter params.
+- `error` — the arcade refused without saying why.
+
+<a id="sharerefusal-key"></a>
+
+## ShareRefusal.key
+
+```ts
+readonly key?: string
+```
+
+The param key that caused it, exactly as you passed it, when one key did.
+
 <a id="shareapi"></a>
 
 ## ShareApi
@@ -15966,24 +16293,33 @@ that a share will happen: the arcade decides that, and does not say.
 ## ShareApi.request
 
 ```ts
-request(request?: ShareRequest): void
+request(request?: ShareRequest): Promise<void>
 ```
 
 Ask the arcade to share a link that opens your game with `params`. Call it
-synchronously from your own Share button's click handler. It returns
-nothing, and nothing ever comes back — not even whether the player shared —
-so never gate progress or a reward on it.
+synchronously from your own Share button's click handler. Nothing about the
+player ever comes back — not even whether they shared — so never gate
+progress or a reward on it.
 
 | Parameter | Type |
 | --- | --- |
 | `request` | `ShareRequest` |
 
+**Returns.** a promise that REJECTS with a [ShareRefusal](#sharerefusal) when the arcade
+  refused the share, naming the reason and the param, and otherwise
+  resolves with nothing. Resolving does not mean the player shared, or saw
+  a sheet at all. An older arcade never refuses out loud, so there it
+  resolves at once.
+
 **Throws.** `Error` when [ShareApi.available](#shareapi-available) is false, and `TypeError`,
   naming the parameter, for one the arcade would refuse: more than 16, a
   key that is not a letter followed by up to 63 letters, digits, `_` or
-  `-`, a key the arcade reserves for itself, or a value that is not a
-  string, is over 512 characters, or holds a control, format or unpaired
-  surrogate character. Nothing is sent when it throws.
+  `-`, a key the arcade keeps for itself, or a value that is not a string,
+  is over 512 characters, or holds a control, format or unpaired surrogate
+  character. Nothing is sent when it throws. Which keys the arcade keeps
+  depends on the arcade: a current one carries reserved keys such as
+  `invite` and refuses only `embedder` (and `_s`, which is not a valid key
+  anyway); an older one refuses all of them.
 
 <a id="playertext"></a>
 

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v20.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v21.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.