@indiegems/gem-web-sdk 13.3.3 → 13.4.1

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v13.3.3, 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` v13.4.1, 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.
 
@@ -333,6 +333,15 @@ from whether the player holds one, which is on [EntityScope](#entityscope).
 Indexed rather than scanned, so a bag render asking for forty definitions
 in a frame stays cheap.
 
+Its `icon_url` is the `icon:` file you uploaded with your config, hosted
+by the platform — the picture the platform's purchase sheet shows. To show
+it in your own shop, pass it through [platformIconUrl](#platformiconurl) and draw your
+placeholder on `undefined`, which is what a development backend answers:
+
+```js
+const src = platformIconUrl(config.item('iron-sword')?.icon_url ?? undefined);
+```
+
 | Parameter | Type |
 | --- | --- |
 | `idOrSlug` | `string` |
@@ -7579,7 +7588,9 @@ numbers to `--gem-safe-top`, `--gem-safe-right`, `--gem-safe-bottom` and
 stylesheet honours them with `var(--gem-safe-top, env(safe-area-inset-top, 0px))`
 and no code — and the rectangles the arcade's controls cover to
 `--gem-reserved-tl-width`, `--gem-reserved-tl-height` and the same pair for
-`tr`, `bl` and `br`. Handle it only for a HUD you position from script — a
+`tr`, `bl` and `br`, with each corner's control centre in
+`--gem-reserved-tl-center-y` and its height in
+`--gem-reserved-tl-control-height`. Handle it only for a HUD you position from script — a
 canvas you draw into, an engine's own UI layer.
 
 <a id="gemoptions-manageaudio"></a>
@@ -8439,8 +8450,13 @@ beside it while the player shows it; an embedder that draws wallets over
 your game adds theirs (see `setWalletVisible`). Keep essential UI and touch
 targets out of them. Empty when the arcade covers nothing.
 
+Each is a keep-out area, grown out to the frame edges it sits nearest — not
+the control's own box, and not something to line anything up with. Where
+the arcade says, `control` on each is the control itself.
+
 A stylesheet reads the per-corner custom properties the SDK stamps from
-these instead — `--gem-reserved-tl-height` and friends.
+these instead — `--gem-reserved-tl-height` and friends, and
+`--gem-reserved-tl-center-y` to line a top bar up with the Gem.
 
 <a id="gemreservedarea"></a>
 
@@ -8494,6 +8510,72 @@ readonly height: number
 
 The rectangle's height.
 
+<a id="gemreservedarea-control"></a>
+
+## GemReservedArea.control
+
+```ts
+readonly control?: GemControlBox
+```
+
+The box of the control this area keeps you out of, as it is drawn — the
+Gem button itself, not grown to the edges — in the same space. Line your
+own controls up with this, never with the area: on a notched phone the
+Gem's area runs up to the top edge, so its middle sits well above the
+button's. Absent under an embedder that does not say, which leaves you the
+keep-out area alone.
+
+<a id="gemcontrolbox"></a>
+
+## GemControlBox
+
+```ts
+interface GemControlBox
+```
+
+The box of one of the arcade's controls over your frame, in the same CSS
+pixels and space as `GemReservedArea`.
+
+<a id="gemcontrolbox-x"></a>
+
+## GemControlBox.x
+
+```ts
+readonly x: number
+```
+
+From your frame's left edge to the control's left edge.
+
+<a id="gemcontrolbox-y"></a>
+
+## GemControlBox.y
+
+```ts
+readonly y: number
+```
+
+From your frame's top edge to the control's top edge.
+
+<a id="gemcontrolbox-width"></a>
+
+## GemControlBox.width
+
+```ts
+readonly width: number
+```
+
+The control's width.
+
+<a id="gemcontrolbox-height"></a>
+
+## GemControlBox.height
+
+```ts
+readonly height: number
+```
+
+The control's height.
+
 <a id="walletvisibleoptions"></a>
 
 ## WalletVisibleOptions
@@ -16955,6 +17037,34 @@ readonly members: readonly RoomMember[]
 
 Everyone in the current room, including this player. Empty when in none.
 
+<a id="roommanager-playwith"></a>
+
+## RoomManager.playWith
+
+```ts
+readonly playWith: PlayWithOutcome | null
+```
+
+What the last [RoomManager.quickJoin](#roommanager-quickjoin) did when the Arcade opened
+your game to play with someone — a friend whose Join the player pressed,
+or their party's leader. Read-only.
+
+- `'joined'` — the player was seated in that person's room, as a member
+  sharing their `groupId`.
+- `'unavailable'` — that room could not be joined (no seat, a match that
+  admits nobody late, another mode), so the quick-join went on as it
+  always does. No reason is given.
+- `null` — no quick-join has asked: the Arcade did not open the game to
+  play with anyone, or nothing has quick-joined yet.
+
+Your game makes no call for this, names nobody and is told nobody's name:
+the Arcade adds a launch key of its own, an opaque ticket, and every
+`quickJoin` passes it on. Nothing else
+changes — the room is the one `quickJoin` answers with, `joined` fires as
+for any quick-join, and no `seated` follows, because your own call made
+the seat. Use it for a line of text ("You joined your friend's game") or
+to skip a mode picker, never to decide anything of value.
+
 <a id="roommanager-on"></a>
 
 ## RoomManager.on
@@ -17461,6 +17571,23 @@ Typed as an open string because the platform may add states. Match the ones
 you handle and treat anything else as unknown rather than switching
 exhaustively.
 
+<a id="playwithoutcome"></a>
+
+## PlayWithOutcome
+
+```ts
+type PlayWithOutcome = "joined" | "unavailable"
+```
+
+What a quick-join did when the Arcade opened your game to play with someone
+— see `gem.rooms.playWith`.
+
+- `joined` — the player was seated in the room of the friend or party mate
+  the Arcade opened the game to play with.
+- `unavailable` — that room could not be joined (no seat, a match that
+  admits nobody late, another mode), so the quick-join went on as it always
+  does. No reason is given, by design.
+
 <a id="matchconnectionstate"></a>
 
 ## MatchConnectionState

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v13.3.3, 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` v13.4.1, 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.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "13.3.3"
+    "version": "13.4.1"
   },
   "entries": [
     {
@@ -430,7 +430,7 @@
           "group": "config",
           "signature": "item(idOrSlug: string): SnapshotItem | null",
           "documented": true,
-          "summary": "One item definition, by id or by slug — either works.\n\n```js\nconst config = await gem.gameConfig.load();\nconst sword = config?.item('iron-sword');\n```\n\n`null` means your config does not define it. That is a different question\nfrom whether the player holds one, which is on [EntityScope](api-reference-game.md#entityscope).\n\nIndexed rather than scanned, so a bag render asking for forty definitions\nin a frame stays cheap.",
+          "summary": "One item definition, by id or by slug — either works.\n\n```js\nconst config = await gem.gameConfig.load();\nconst sword = config?.item('iron-sword');\n```\n\n`null` means your config does not define it. That is a different question\nfrom whether the player holds one, which is on [EntityScope](api-reference-game.md#entityscope).\n\nIndexed rather than scanned, so a bag render asking for forty definitions\nin a frame stays cheap.\n\nIts `icon_url` is the `icon:` file you uploaded with your config, hosted\nby the platform — the picture the platform's purchase sheet shows. To show\nit in your own shop, pass it through [platformIconUrl](api-reference-game.md#platformiconurl) and draw your\nplaceholder on `undefined`, which is what a development backend answers:\n\n```js\nconst src = platformIconUrl(config.item('iron-sword')?.icon_url ?? undefined);\n```",
           "deprecated": null,
           "params": [
             {
@@ -8678,7 +8678,7 @@
           "group": "start",
           "signature": "readonly onViewport?: (viewport: GemViewport) => void",
           "documented": true,
-          "summary": "Which part of your game's own box is unsafe to draw essential UI in arrived,\nor changed — the display cutout, the home indicator, the arcade's own\ncontrols beside your frame.\n\n**Most games need no handler.** The SDK has already written the same four\nnumbers to `--gem-safe-top`, `--gem-safe-right`, `--gem-safe-bottom` and\n`--gem-safe-left` on your document's root before this fires, so a\nstylesheet honours them with `var(--gem-safe-top, env(safe-area-inset-top, 0px))`\nand no code — and the rectangles the arcade's controls cover to\n`--gem-reserved-tl-width`, `--gem-reserved-tl-height` and the same pair for\n`tr`, `bl` and `br`. Handle it only for a HUD you position from script — a\ncanvas you draw into, an engine's own UI layer.",
+          "summary": "Which part of your game's own box is unsafe to draw essential UI in arrived,\nor changed — the display cutout, the home indicator, the arcade's own\ncontrols beside your frame.\n\n**Most games need no handler.** The SDK has already written the same four\nnumbers to `--gem-safe-top`, `--gem-safe-right`, `--gem-safe-bottom` and\n`--gem-safe-left` on your document's root before this fires, so a\nstylesheet honours them with `var(--gem-safe-top, env(safe-area-inset-top, 0px))`\nand no code — and the rectangles the arcade's controls cover to\n`--gem-reserved-tl-width`, `--gem-reserved-tl-height` and the same pair for\n`tr`, `bl` and `br`, with each corner's control centre in\n`--gem-reserved-tl-center-y` and its height in\n`--gem-reserved-tl-control-height`. Handle it only for a HUD you position from script — a\ncanvas you draw into, an engine's own UI layer.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9556,7 +9556,7 @@
           "group": "player",
           "signature": "readonly reserved: readonly GemReservedArea[]",
           "documented": true,
-          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in whichever corner it sits, and the frame-rate readout\nbeside it while the player shows it; an embedder that draws wallets over\nyour game adds theirs (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
+          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in whichever corner it sits, and the frame-rate readout\nbeside it while the player shows it; an embedder that draws wallets over\nyour game adds theirs (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nEach is a keep-out area, grown out to the frame edges it sits nearest — not\nthe control's own box, and not something to line anything up with. Where\nthe arcade says, `control` on each is the control itself.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends, and\n`--gem-reserved-tl-center-y` to line a top bar up with the Gem.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9645,6 +9645,102 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemReservedArea.control",
+          "name": "control",
+          "anchor": "gemreservedarea-control",
+          "group": "player",
+          "signature": "readonly control?: GemControlBox",
+          "documented": true,
+          "summary": "The box of the control this area keeps you out of, as it is drawn — the\nGem button itself, not grown to the edges — in the same space. Line your\nown controls up with this, never with the area: on a notched phone the\nGem's area runs up to the top edge, so its middle sits well above the\nbutton's. Absent under an embedder that does not say, which leaves you the\nkeep-out area alone.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlBox",
+          "name": "GemControlBox",
+          "anchor": "gemcontrolbox",
+          "group": "player",
+          "signature": "interface GemControlBox",
+          "documented": true,
+          "summary": "The box of one of the arcade's controls over your frame, in the same CSS\npixels and space as `GemReservedArea`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlBox.x",
+          "name": "x",
+          "anchor": "gemcontrolbox-x",
+          "group": "player",
+          "signature": "readonly x: number",
+          "documented": true,
+          "summary": "From your frame's left edge to the control's left edge.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlBox.y",
+          "name": "y",
+          "anchor": "gemcontrolbox-y",
+          "group": "player",
+          "signature": "readonly y: number",
+          "documented": true,
+          "summary": "From your frame's top edge to the control's top edge.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlBox.width",
+          "name": "width",
+          "anchor": "gemcontrolbox-width",
+          "group": "player",
+          "signature": "readonly width: number",
+          "documented": true,
+          "summary": "The control's width.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlBox.height",
+          "name": "height",
+          "anchor": "gemcontrolbox-height",
+          "group": "player",
+          "signature": "readonly height: number",
+          "documented": true,
+          "summary": "The control's height.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "WalletVisibleOptions",
           "name": "WalletVisibleOptions",
@@ -18878,6 +18974,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RoomManager.playWith",
+          "name": "playWith",
+          "anchor": "roommanager-playwith",
+          "group": "rooms",
+          "signature": "readonly playWith: PlayWithOutcome | null",
+          "documented": true,
+          "summary": "What the last [RoomManager.quickJoin](api-reference-game.md#roommanager-quickjoin) did when the Arcade opened\nyour game to play with someone — a friend whose Join the player pressed,\nor their party's leader. Read-only.\n\n- `'joined'` — the player was seated in that person's room, as a member\n  sharing their `groupId`.\n- `'unavailable'` — that room could not be joined (no seat, a match that\n  admits nobody late, another mode), so the quick-join went on as it\n  always does. No reason is given.\n- `null` — no quick-join has asked: the Arcade did not open the game to\n  play with anyone, or nothing has quick-joined yet.\n\nYour game makes no call for this, names nobody and is told nobody's name:\nthe Arcade adds a launch key of its own, an opaque ticket, and every\n`quickJoin` passes it on. Nothing else\nchanges — the room is the one `quickJoin` answers with, `joined` fires as\nfor any quick-join, and no `seated` follows, because your own call made\nthe seat. Use it for a line of text (\"You joined your friend's game\") or\nto skip a mode picker, never to decide anything of value.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RoomManager.on",
           "name": "on",
@@ -19474,6 +19586,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayWithOutcome",
+          "name": "PlayWithOutcome",
+          "anchor": "playwithoutcome",
+          "group": "rooms",
+          "signature": "type PlayWithOutcome = \"joined\" | \"unavailable\"",
+          "documented": true,
+          "summary": "What a quick-join did when the Arcade opened your game to play with someone\n— see `gem.rooms.playWith`.\n\n- `joined` — the player was seated in the room of the friend or party mate\n  the Arcade opened the game to play with.\n- `unavailable` — that room could not be joined (no seat, a match that\n  admits nobody late, another mode), so the quick-join went on as it always\n  does. No reason is given, by design.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "MatchConnectionState",
           "name": "MatchConnectionState",

package/docs/changelog.md

@@ -16,6 +16,26 @@ 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.
 
+## 13.4.1
+
+Upgrading from 13.4.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 13.4.0
+
+Upgrading from 13.3.3. Impact: required.
+
+### Rebuild
+
+- The reserved areas accepted by GemHost.sendViewport and the reserved list on GemViewport now allow an optional control box on each area. The field is additive and optional, so existing code keeps working. Recompile your game; no code change is needed unless you want to use the new field.
+
+### New capability
+
+- Each reserved area can now carry the box of the control inside it, with x, y, width and height. Reserved areas are keep-out zones that extend to the frame edges, so their middle is not the middle of the control. When you want to align your own interface with the Arcade control, for example to centre a top bar on it, read the control box from the area instead of deriving it from the keep-out zone. The field is absent for an area with no control, so check for it first.
+- The room manager now exposes a read-only playWith value. When the Arcade opens your game to play with a friend or party member, a quick-join may land the player in that person's room. The value tells your game whether the player joined somebody or no such room was available. It is null when the game was not opened this way, and it never says who the other player is. Use it to adjust your lobby or welcome messaging.
+- Catalog recipes now include an icon_url field with the platform-hosted icon. The Arcade purchase sheet already draws this icon, and your game can show the same icon in its own shop or inventory screens instead of shipping a separate copy.
+
 ## 13.3.3
 
 Upgrading from 13.3.2. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "13.3.3"
+  "@indiegems/gem-web-sdk": "13.4.1"
 }
 ```
 
@@ -347,13 +347,18 @@ const jarIndex = Number.isInteger(n) && n >= 1 && n <= JAR_COUNT ? n : null;
 
 That is the whole contract for your own keys. The bridge carries no launch message, and the SDK
 has no API for them: the arcade does the forwarding, so a build you published on any SDK version
-gets it without a code change. The one key that is not yours is the platform's `gemChallenge`
-(below), which belongs to [friend challenges](friends.md#friend-challenges): never define it, and
-never parse it yourself. The SDK reads it for you — `gem.friends.launchedChallenge()` answers the
-challenge it names, or `null` — and that is the only launch key it will ever read. It is read once,
-when `createGem` runs, so cleaning your URL afterwards does not lose it. Call `createGem` before
-you clean the URL, or leave `gemChallenge` in place: a key removed before `createGem` runs is never
-seen, and `launchedChallenge()` then resolves `null` with no error.
+gets it without a code change. Two keys are not yours, and they are the platform's (below):
+`gemChallenge`, which belongs to [friend challenges](friends.md#friend-challenges), and
+`gemPlayWith`, an opaque ticket the arcade adds when it opens your game to play with a friend or a
+party mate, which names nobody your game can recognise. Never define either, and never parse
+either yourself. The SDK reads them for you —
+`gem.friends.launchedChallenge()` answers the challenge `gemChallenge` names, or `null`, and every
+`gem.rooms.quickJoin()` passes `gemPlayWith` on
+([Landing in a friend's room](rooms-and-matches.md#5e-landing-in-a-friends-room-play-with)) — and
+they are the only launch keys it reads. Each is read once, when `createGem` runs, so cleaning your
+URL afterwards does not lose it. Call `createGem` before you clean the URL, or leave both keys in
+place: a key removed before `createGem` runs is never seen, so `launchedChallenge()` resolves
+`null` with no error and a quick-join plays with nobody.
 
 What reaches the frame:
 
@@ -375,11 +380,12 @@ What reaches the frame:
   A key starting with `_` can never be one of yours: the key rule below requires a leading
   letter, so the arcade keeps that space for itself.
 
-- **One platform key.** `gemChallenge` does reach the frame — the arcade adds it when a player
-  opens a friend challenge — but it is the platform's, not yours: read the challenge with
-  `gem.friends.launchedChallenge()`, never from the URL. Do not define a key of that name, and
-  treat every key beginning with `gem` as reserved: a friend-challenge template refuses a param
-  named that way.
+- **Two platform keys.** `gemChallenge` and `gemPlayWith` do reach the frame — the arcade adds the
+  first when a player opens a friend challenge, and the second when it opens your game to play
+  with someone — but they are the platform's, not yours: read the challenge with
+  `gem.friends.launchedChallenge()`, let `gem.rooms.quickJoin()` carry `gemPlayWith`, and never
+  read either from the URL. Do not define a key of either name, and treat every key beginning
+  with `gem` as reserved: a friend-challenge template refuses a param named that way.
 - **Bounded.** At most 16 parameters. A key is a letter followed by up to 63 letters, digits,
   `_` or `-`. A value is at most 512 characters with no control or format characters. An entry
   that breaks a rule is dropped on its own; the rest of the link still arrives.

package/docs/inventory-and-catalogs.md

@@ -696,6 +696,27 @@ game `busy` for a short, growing interval — do not re-ask on `cancelled`.
 Hide this specific affordance when `gem.frame.parentSupports('purchases')` is false. That check does
 not apply to the direct SDK path.
 
+The sheet shows the item's or recipe's picture from its `icon_url`. You never write that field: it
+is the `icon:` file you upload with your config (`icon: icons/extra-life.png` in the YAML, uploaded
+by `gemctl config upload`), which the platform hosts and fills in. A recipe with no `icon:` of its
+own shows the icon of the one item it grants. With neither, the sheet shows its default picture.
+
+Your own shop can show the same picture. Pass the URL through `platformIconUrl` first, from the
+package you installed in [Getting started](getting-started.md), and draw your own placeholder when
+that answers `undefined`:
+
+```js
+import { platformIconUrl } from '@indiegems/gem-web-sdk/sdk';
+
+const src = platformIconUrl(config.item('extra-life')?.icon_url ?? undefined);
+if (src) img.src = src;
+else drawPlaceholder();
+```
+
+A recipe's icon is the `icon_url` on the recipe in `config.catalogs[].recipes`; read it the same
+way. `platformIconUrl` passes only the platform's production image host, so against a development
+backend it answers `undefined` by design: there, your placeholder is what you see.
+
 #### Game-owned direct purchase
 
 Use the direct path when your game provides its own purchase UI and does not want the platform sheet:

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "10d8155b80d2e8233ef9b489a4ad20a46e89e01447ebbc23acc86aaeb2dbc73e",
-      "updated": "2026-10-16T18:11:54Z"
+      "sha256": "94baa26268843ba926462633ddec8aaca56aabf79ee6639aaf77df68474debc7",
+      "updated": "2026-10-17T00:33:31Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -38,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "854389e510b125afc6fdd075d19db655388330faa676a82a888a1447b9973e2b",
-      "updated": "2026-10-16T20:36:38Z"
+      "sha256": "68726bcd339a18e0fc6b5b9fdfe5ca3666e1c1fb79293a64c361e09616c87a85",
+      "updated": "2026-10-18T17:04:31Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,13 +68,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "32cc41ca951169e902f39493d9d912ca55d67f906e83066217fb38b62680ab1e",
-      "updated": "2026-10-16T20:36:38Z"
+      "sha256": "5f950537b4a4d1f952adbc294fdba8bdd05ebaf6d8a924951129ff604b31f3d8",
+      "updated": "2026-10-18T17:04:31Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "4251f451c48ab80bb7a9c50a6a717dfca6e057ff128d32ecb5e2cd13d28c5b7d",
-      "updated": "2026-10-14T21:18:16Z"
+      "sha256": "fc2dbf113d2602fff90d03fc24e03d468c7b4ab3633844ed9d0df6b985e69385",
+      "updated": "2026-10-18T00:39:23Z"
     },
     {
       "file": "leaderboards.md",
@@ -88,8 +88,8 @@
     },
     {
       "file": "p2p-and-parties.md",
-      "sha256": "3887bc706d098014cefab84e9b8bd5b964841888c242a7ccb1f799a9b9723fc0",
-      "updated": "2026-09-24T01:00:22Z"
+      "sha256": "4cfe2a47def51eb617f154eaac39faf176d8aa7ca2c36907084b6349048ab1b9",
+      "updated": "2026-10-17T22:11:15Z"
     },
     {
       "file": "platform-moments.md",
@@ -108,8 +108,8 @@
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "a99363a8eb6e8e5978c24a283e2a606efce1308b05039b9fb82ec06f39a3213c",
-      "updated": "2026-10-16T19:17:27Z"
+      "sha256": "a111ae68fb0d443f8c183c7a963668078a6d155124cf19da45391218c0716e1f",
+      "updated": "2026-10-17T17:23:21Z"
     },
     {
       "file": "room-shapes.md",
@@ -118,8 +118,8 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "29cf42a4334d3d9702e6a7f6e04c52fb2b414af3340043c2f98b2bfafa7dc64d",
-      "updated": "2026-10-12T19:59:08Z"
+      "sha256": "8f5879028034a75dfd14dc6afa71d96e1c3203ba1969f00b39c2dad043818963",
+      "updated": "2026-10-17T22:11:15Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "a53c08888a4eff98e84d2876f461c119125fd44a74a6f4f787ba910920bf59fc",
-      "updated": "2026-10-16T20:36:38Z"
+      "sha256": "056d725c06e61dc6ebdda3fe082809a416ce7f87f2e84879bc0971c6065ba4f9",
+      "updated": "2026-10-18T17:04:31Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "e97ca7a5b01a40d57900eb1116e961768f62bccfd412afd02bca245cdb7beeab",
-      "updated": "2026-10-15T20:36:02Z"
+      "sha256": "97f97817fb087dbe2c637b4ea7f22f1ab624496bd32e427e4619c211c65d4f21",
+      "updated": "2026-10-18T15:05:29Z"
     }
   ]
 }

package/docs/p2p-and-parties.md

@@ -568,9 +568,10 @@ one this SDK calls. A v2 member row carries `group_id`; no party id appears
 anywhere in the response, at any level — not even the requester's own.
 
 `RoomMember.groupId` is that value, read off the wire. Two members sharing it
-arrived together; a member with no value arrived alone. It is opaque: draw a badge
-with it, group a roster by it, compare two members' values — but do not parse it,
-key anything off it, or keep it once the room is gone.
+arrived together — as a party, or one coming to play with the other (§7.5 and
+`rooms-and-matches.md` §5e); a member with no value arrived alone. It is opaque:
+draw a badge with it, group a roster by it, compare two members' values — but do
+not parse it, key anything off it, or keep it once the room is gone.
 
 The stability across rooms is precisely what was removed: the marker is scoped to
 one room, so the same party in two rooms carries two unrelated values. The useful
@@ -708,6 +709,34 @@ cleared, and the SDK raises a refusal that names the party cause — because a g
 that just ran the documented recovery has every reason to think the room is gone.
 Adopting is the answer there too: the room to be in is the one the party is in.
 
+### 7.5 A member who opens the game after the leader: play-with
+
+A member who was not in your game when their leader started it — browsing the
+Arcade, or in another game — is not left to find it. The Arcade shows them a
+prompt, and its Join opens your game **to play with the leader**: the launch key
+`gemPlayWith` that `rooms-and-matches.md` §5e describes, an opaque ticket that
+names nobody your game can recognise. Your game makes no call for it. Its own
+`quickJoin()` carries the ticket, and the platform seats the member in the
+leader's room when it has a seat, because the two are in one party.
+
+What the member's game sees is an ordinary quick-join:
+
+- **The room it asked for answers, and `gem.rooms.playWith` reads `'joined'`.**
+  `'unavailable'` means the leader's room could not be joined — full, of another
+  mode, or in a match that admits nobody late — and the quick-join went on as
+  usual.
+- **No `seated` fires for it**, because the member's own call made the seat.
+  Keep the `seated` handler (§7.4) all the same: it is still how a member who
+  was already in your game when the leader started is brought in.
+- **The member shares the party's `groupId`**, so a roster that groups the party
+  shows them with it.
+- **It holds its own seat.** A member seated by the leader's call leaves only
+  with the group (§7.4); one who came in this way arrived by their own call, so
+  they can leave alone, and the leader taking the party out does not take them.
+
+The leader's game does nothing new either. Its quick-join is the party's room
+call, as before, and plays with nobody else.
+
 ---
 
 ## 8. Capabilities