@indiegems/gem-web-sdk 11.1.2 → 12.0.0

package/docs/changelog.md

@@ -16,6 +16,20 @@ 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.
 
+## 12.0.0
+
+Upgrading from 11.1.2. Impact: required.
+
+### Rebuild
+
+- The list of capability names gained ticketEvents. Recompile your game. If your code switches exhaustively over capability names, add a case for the new one.
+- The list of messages the parent sends to the frame, and the union of parent message types, each gained a ticket event message. Recompile your game. If your code switches exhaustively over these message names or types, handle or ignore the new one.
+
+### New capability
+
+- A party member's game can now show the matchmaking ticket its party is queued on. Read the ticket through the rooms manager, or listen for the new partyQueued room event. The view is read-only: it has a status, a party size, two instants and an outcome, and it cannot be cancelled. A matched ticket does not carry the room. The room is reported separately once the SDK has confirmed the player is seated in it. The view ends on its own as lost once the ticket's lifetime has passed with no ending heard. For the player who queued, the ticket still comes from the platform's own answer.
+- Games that build their own frame can now pass an onTicketEvent callback to receive ticket state changes pushed by the parent. It is delivered only when the parent relays ticket events and advertises the new ticketEvents capability. Under a parent that does not, nothing changes and the callback is never called. Ticket events name no player and do not carry the templates a ticket named.
+
 ## 11.1.2
 
 Upgrading from 11.1.1. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "11.1.2"
+  "@indiegems/gem-web-sdk": "12.0.0"
 }
 ```
 
@@ -66,7 +66,10 @@ is involved, and nothing is built when you install.
 **`/sdk` is the import, from every seat.** It carries the whole surface, so client code, a
 dedicated server bundle and a listen host all import the same path and the same names.
 `.`, `/game` and `/server` stay published as narrow doors over the same modules — a game
-wants none of them unless it knows why.
+wants none of them unless it knows why. `/function` is the fourth door, for code that runs as
+a serverless function ([serverless-functions-js.md](serverless-functions-js.md)). The function
+starter's build resolves `/sdk` and `/game` to it, so verification code shared with your game
+keeps its import.
 
 **`dependencies`, not `devDependencies`.** The SDK is part of what your game ships — your
 bundler compiles it into the browser build and into the server bundle — so a `--production`

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "f88799ff04404b0ad76c5774375a66772c9ed7a64b59ca566f473f1302c9b2d7",
-      "updated": "2026-10-12T17:30:48Z"
+      "sha256": "bf2786be31121bb229d10d98f701165aefb2e7166271299450c926401661dfd2",
+      "updated": "2026-10-12T22:12:20Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "4a824bccf87d75c2884a7159b44c768b39096f815b80fa7b5018da2862add89e",
-      "updated": "2026-10-12T17:30:48Z"
+      "sha256": "19bf05cd8f7afe5e9f406af6aef090a73bb3c2fb713f06185ead36fc2bb104dc",
+      "updated": "2026-10-12T22:12:20Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,8 +113,8 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "971e67d9cb74a046cddc0ff76cdea64f1aef3af8e9376944388ca8aa87730729",
-      "updated": "2026-10-12T02:26:43Z"
+      "sha256": "29cf42a4334d3d9702e6a7f6e04c52fb2b414af3340043c2f98b2bfafa7dc64d",
+      "updated": "2026-10-12T19:59:08Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -123,18 +123,18 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "f1ff81f3ee1950dae0d8b0fab66994eeec99d6e6bf1684b121c742f29d63e0b9",
-      "updated": "2026-10-12T17:30:48Z"
+      "sha256": "52054ceeb56b7130bfaf3461c2d81a9bd3b3dcd0f95097753ebfffc08f7a1cbb",
+      "updated": "2026-10-12T22:12:20Z"
     },
     {
       "file": "serverless-functions-js.md",
-      "sha256": "56588d50d5a59f066164565470663f8f9da03fe85d98a96d3754e6ec14eb9fac",
-      "updated": "2026-10-10T00:12:33Z"
+      "sha256": "3904704418f9c6c246c8e1fa83f96901f6e493a3f4499b16fd6845620515e57d",
+      "updated": "2026-10-12T17:39:05Z"
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "b1562b4442b69bb6895198def7b00ccd7a8c56133862a939c2cce9b6e9d30290",
-      "updated": "2026-10-07T19:27:16Z"
+      "sha256": "84881bcc40c6203c731ebf9092be575158d0ad3b3a65120321b695ae6558f63f",
+      "updated": "2026-10-12T17:39:05Z"
     },
     {
       "file": "trading-and-gifting.md",

package/docs/rooms-and-matches.md

@@ -140,6 +140,13 @@ frame that advertises `autoStartFailure`. It is not a sixth `gem.roomEvent` beca
 refuses an enum value it does not know, and reports that to the game as a protocol error; an unknown
 message type it ignores. The game sees it as `matchAutoStartFailed` (§4.4).
 
+**The matchmaking-ticket pushes cross the same way**, as `gem.ticketEvent`, to a frame that
+advertises `ticketEvents`. The platform tells every player a ticket seats when it is created,
+matched, or ended without a match, and the parent relays each one for the frame's own game: the
+ticket's id and new status, plus the party size and the two instants on creation, the reason on an
+ending without a match, and the room to look in on a match. The templates the ticket named do not
+cross, and no player is named on either side of the bridge. What a game does with it is §5c.
+
 There is exactly one filtering point and this is it. The engine keeps a full match event in native
 code and hands its scripting layer an allowlisted subset, because native code can hold a secret
 from a sandboxed script. **The frame-side SDK cannot** — it shares a JavaScript realm with the game,
@@ -794,11 +801,15 @@ every game.
   platform sends the push a moment before it marks the ticket. So on a page that relays, a match is
   noticed in about the time the push takes, not at the next heartbeat. A tab returning to the
   foreground is the same cue. Like every relay it is a hint: nothing is entered on its strength.
+  **A relayed ticket push is the same cue**, so an ending without a match is noticed as quickly as a
+  match is. The ticket's outcome still comes from the platform's answer, never from the push.
 - **It refuses a second thing in flight.** While a ticket waits, `create`, `join`, `joinByCode`,
   `quickJoin` and another `queueForMatch` are refused locally.
 - **It cancels the ticket when the tab closes.** See below.
 - **It raises no `seated` for the ticket's own room.** The owner is told by the outcome. Party
-  members, who hold no ticket, are told by `seated` as they are for any room their leader enters.
+  members, who hold no ticket, are told by `seated` as they are for any room their leader enters —
+  and, on a page that relays ticket events, by `partyQueued` while the party waits. See
+  [A party member's view](#a-party-members-view-of-the-ticket).
 
 ### Queueing from inside a room
 
@@ -862,6 +873,58 @@ seat stands, so `myRooms()` shows the room and `join(id)` enters it.
 `cancel()` resolves the ticket's real outcome, and that may be `matched`. Backing out from there is
 `gem.rooms.leave()`.
 
+### A party member's view of the ticket
+
+A party queues as **one ticket, and it is the leader's**. Only the leader calls `queueForMatch()`,
+and only a ticket's owner can read it, keep it alive or cancel it. So a member's game holds no
+ticket — and without help it knows nothing about the queue its player is standing in until the match
+pulls them in.
+
+On an arcade page that relays ticket events, the member's game is told. When the leader queues,
+`gem.rooms.partyTicket` is set and `partyQueued` is raised with it:
+
+```js
+gem.rooms.on('partyQueued', async (ticket) => {
+  showSearching({ expiresAt: ticket.expiresAt, canCancel: false });
+  const outcome = await ticket.outcome;
+  if (outcome.status !== 'matched') backToMenu(outcome.status);
+  // `matched`: the room arrives through your `seated` handler.
+});
+```
+
+- **It is a view. There is no `cancel()`.** The ticket is the leader's to cancel. A member who wants
+  out leaves the party, which ends the ticket for everyone with reason `party_changed`. Draw the
+  searching screen without a leave-queue button.
+- **It costs no request.** Nothing is heartbeated and nothing is polled for it; everything the view
+  says came from a relayed push.
+- **`matched` carries no room.** The room is reported the way a party's seat always is, the `seated`
+  event, and that handler is where a game joins it. The SDK looks for the seat as soon as it hears
+  `matched`, and reports it only after reading the room over the game's own token and finding this
+  player in it.
+- **It ends by itself.** The pushes are sent once. A member's game that missed the ending would
+  otherwise show a searching screen for ever, so the view ends as `lost` a few seconds after the
+  ticket's lifetime has run out with nothing more heard. A seat found by the SDK's own seat check
+  ends it as `matched`, whether or not that push arrived.
+- **Never set beside `currentTicket`.** The player who queued holds the ticket itself and gets no
+  `partyQueued`.
+
+| `status` | `reason` | What happened |
+| --- | --- | --- |
+| `matched` | — | The party is seated and the match is starting. `seated` has the room. |
+| `expired` | `timed_out` | Nobody to play with before the ticket's expiry. |
+| `expired` | `heartbeat_lapsed` | The leader's game stopped keeping the ticket alive: a closed, throttled or offline tab. |
+| `cancelled` | `requested` | The leader cancelled. |
+| `cancelled` | `party_changed` | The party gained or lost a member while it waited. |
+| `failed` | `handoff_failed` | A match formed and could not be started, several times over. |
+| `lost` | — | The SDK's own conclusion: the ticket's lifetime ran out and no ending was heard. |
+
+⚠️ **Build it as an extra, never as a step.** The view exists only where the page relays ticket
+events, and only for a game that was already running when the leader queued: a push sent before the
+game was listening is not sent again. In every other case `partyTicket` stays `null`, no
+`partyQueued` is raised, and the member is carried into the match by `seated` with no lead-up. That
+path has to keep working, so the `seated` handler is what enters the match and the searching screen
+is only something shown on the way.
+
 ### The refusals when queueing
 
 `queueForMatch()` itself rejects with `GemApiError` when no ticket was made. Branch on `code`:

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v11.1.2/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v11.1.2/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v12.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v12.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/serverless-functions-js.md

@@ -1,9 +1,5 @@
 # Serverless functions in JavaScript
 
-**The platform does not run JavaScript functions yet.** This page describes how one is written
-and how it behaves; today a function you publish is a WebAssembly component, as
-[serverless-functions.md](serverless-functions.md) describes.
-
 A serverless function can be written in JavaScript or TypeScript instead of Rust: the language your
 game is already written in, so the verification code in your browser game moves into a function
 with no change beyond bundling. You upload one bundled ES module, and the platform runs it on a
@@ -51,31 +47,46 @@ are read and written:
 | `handle(input)`     | `Uint8Array`: the request body, byte for byte         | `Uint8Array`, `ArrayBuffer` or `string` (sent as UTF-8); anything else is an error                        |
 | `handleJson(input)` | the body parsed as JSON; an empty body is `undefined` | any JSON-serializable value, sent as its JSON text; `undefined` is sent as `null`; a `BigInt` is an error |
 
-Either may be `async`; the platform waits for the promise. Exporting neither, or both, is refused
-when you upload. A caller cannot tell which kind of function answered: `gem.functions.invoke`, the
-limits and the refusals in serverless-functions.md are identical for both.
+Either may be `async`; the platform waits for the promise, and a promise that never settles fails
+the call. Exporting neither, or both, is refused when you upload. A caller cannot tell which kind of
+function answered: `gem.functions.invoke`, the limits and the refusals in serverless-functions.md
+are identical for both.
+
+**Each call gets the same limits as a component:** 5 seconds of wall clock, 1 second of CPU,
+256 MiB of memory, 32 platform calls, 256 KiB of input and 1 MiB of output, and the module itself
+may be at most 32 MiB. The full list is
+[the limits on one call](serverless-functions.md#the-limits-on-one-call).
 
 **A thrown exception is `Err`.** The call fails with `function_error`, and `err.functionMessage` is
 the exception's `name: message` (a thrown value that is not an `Error` is its `String()`). The
-message and the stack go to the platform's log for the invocation, never to the caller. A
-`handleJson` whose input is not JSON, or whose return value JSON cannot carry, fails the same way.
+message and the stack are also logged for the invocation at `error`; the stack never reaches the
+caller. A `handleJson` whose input is not JSON, or whose return value JSON cannot carry, fails the
+same way.
 
 **`console.*` reaches the invocation's log** at the matching level (`debug`, `info`, `warn`,
 `error`); `console.log` and every other method log at `info`. As with a component's `log`,
 `gemctl function logs` reads it back for a call on `dev`, and a call on `test` or `release` keeps
-no line.
+no line. Each line is cut at 1 KiB, and one call keeps at most **100 lines or 64 KiB** of them,
+whichever comes first. Every `console` call past that goes unrecorded, and the call's closing log
+line counts them in `dropped_log_lines` (serverless-functions.md section 7).
 
 ## 2. Writing one
 
 ```bash
 gemctl function init --lang js functions/score-check
-cd functions/score-check && npm install && npm run build
-gemctl function upload dist/function.js
+(cd functions/score-check && npm install && npm run build)
+gemctl function upload --file functions/score-check/dist/function.js --version 1.0.0
+gemctl function promote 1.0.0 --channel dev
 ```
 
 **`init --lang js`** writes a `package.json` whose `build` script type-checks and then bundles to
-one ES module, a TypeScript starter handler and a `tsconfig.json`. gemctl runs neither step:
-`npm run build` is yours, the way `cargo build` is for a component.
+one ES module in `dist`, a TypeScript starter handler and a `tsconfig.json`. gemctl runs neither
+step: `npm run build` is yours, the way `cargo build` is for a component. The starter lists the SDK
+in `devDependencies`, and its build bundles the SDK into the one module you upload. Nothing is
+provided to a function you upload now, so that module is the whole of your function. That is why
+the SDK is a dev dependency here while [getting-started.md](getting-started.md) puts it in
+`dependencies` for a game: what a game ships is built from its install, and what a function ships
+is the bundle.
 
 A handler looks like this:
 
@@ -96,23 +107,38 @@ The package is the one your game already depends on, installed as
 serverless-functions.md section 1, and it applies unchanged: a save or a setting the player's own
 browser can write is the player's claim, not evidence.
 
-**Imports.** The module may import the SDK and nothing else, under any of the three names a game
-already uses: `@indiegems/gem-web-sdk/function`, `@indiegems/gem-web-sdk/sdk`, or
-`@indiegems/gem-web-sdk/game`. Inside a function all three are the same module, the function
-entry, so shared code keeps its import. A name that module does not export, such as
-`defineServer`, fails every call with `function_error`. Everything else your code needs is bundled
-in, which is what the starter's build does. An `import()` at runtime is refused at upload.
-Top-level `await` is allowed and runs on every call.
-
-**What the engine gives you.** `Date`, `performance`, `Math.random`, `crypto.getRandomValues`,
-`crypto.randomUUID`, `TextEncoder`, `URL` and `fetch` all work. `fetch` reaches only the platform
-API, through the SDK, and the save links the platform hands you; any other URL is refused. A timer
-waits at most 10 ms: a function has no reason to sleep, and a long one would run out the wall
-clock.
-
-**The SDK version your function runs is the one the platform bundles**, not the one in your
-`package.json`; the starter pins the matching version. A method added in a newer SDK reaches a
-function when the platform's engine picks that version up.
+**Imports.** The module you upload imports nothing. Everything it uses, the SDK included, is
+bundled into it, which is what the starter's build does. A file shared with your game may keep its
+`@indiegems/gem-web-sdk/sdk` or `@indiegems/gem-web-sdk/game` import, because the starter's build
+resolves both to `@indiegems/gem-web-sdk/function` when it bundles your function. A name the
+function entry does not export, such as `defineServer`, then fails the build rather than a call.
+For a function still on the engine's built-in copy (below) the same name fails the call with
+`function_error`. An `import()` at runtime is refused at upload. Your module is evaluated afresh
+for every call, so its top level, including any top-level `await`, runs on every call and inside
+that call's limits; the engine's built-in copy, by contrast, was evaluated once when the engine was
+built, which is one reason it stays at 7.6.0.
+
+**What the platform gives your function.** `fetch`, `URL`, `URLSearchParams`, `TextEncoder`,
+`TextDecoder`, `AbortController`, `AbortSignal.timeout`, `setTimeout`, `setInterval`,
+`crypto.randomUUID`, `crypto.getRandomValues`, `atob`, `btoa`, `console`, `Date` and `Math.random`
+all work. `fetch` reaches only the platform API, through the SDK, and the save links the platform
+hands you; any other URL is refused before anything is sent, and every request counts toward the
+call's platform-call limit. Timers and `AbortSignal.timeout` wait their full length, and the engine
+sets no limit of its own: what bounds a wait is the call's wall clock, and a call still waiting when
+it runs out fails with `function_timeout`. A wait spends wall clock, not CPU.
+
+**The SDK your function runs is the one you bundle.** A function published importing the SDK from
+the engine runs the engine's built-in copy instead (the next paragraph). The starter's build
+bundles the version your `package.json` names, so pin the version your game pins and the same code
+runs in both places. A method added in a newer SDK reaches your function when you bundle that
+version: update the pin, build, upload and promote.
+
+**A function published importing the SDK from the engine** (the earlier starter marked it external)
+keeps running on the engine's built-in copy, gem-web-sdk 7.6.0, which is not updated and is removed
+once no published function imports it. Nothing fails at an engine roll. A new upload cannot import
+it: the platform refuses every import, so a function moves off the built-in by a rebuild with the
+current starter's build (which bundles the SDK), an upload of a new version and a promote. A method
+added in a newer SDK reaches a function only when that version is bundled.
 
 ## 3. The SDK inside a function
 
@@ -120,8 +146,47 @@ function when the platform's engine picks that version up.
 `awaitIdentity()` resolve at once, and `gem.me` is the player who called. So a game's boot sequence
 runs unchanged, and the same `gem.me.saves.get`, `gem.leaderboards.get` and `gem.profiles.of` calls
 work, with the same types and the same errors. The function's game and channel come from the call;
-nothing you write names them. `gem.context` is who called, for which game and channel, and
-`gem.identity` is the same three fields a browser game reads from its own `gem.identity`.
+nothing you write names them.
+
+```ts
+function createGem(options?: unknown): GemFunction; // options is accepted and ignored
+```
+
+| Member            | Type                           | What it is                                                            |
+| ----------------- | ------------------------------ | --------------------------------------------------------------------- |
+| `context`         | `FunctionContext`              | Who called, for which game and channel, and this call's invocation id |
+| `identity`        | `GemFunctionIdentity \| null`  | `playerId`, `gameId` and `channel`; `null` when a game server called  |
+| `awaitIdentity()` | `Promise<GemFunctionIdentity>` | `identity`, at once; rejects when a game server called                |
+| `awaitBridge()`   | `Promise<'connected'>`         | `'connected'`, at once                                                |
+| `me`              | `EntityScope`                  | The calling player's settings, inventory, currencies and saves        |
+| `characters`      | `CharactersApi`                | The calling player's characters                                       |
+| `transfers`       | `TransfersApi`                 | Moving items and currency between players                             |
+| `analytics`       | `AnalyticsApi`                 | Your game's analytics, as the calling player                          |
+| `leaderboards`    | `LeaderboardsApi`              | The leaderboards your game config declares                            |
+| `challenges`      | `ChallengesApi`                | Daily challenge periods and subjects                                  |
+| `showcase`        | `ShowcaseApi`                  | Display-only values other players may read                            |
+| `friends`         | `FriendsApi`                   | The calling player's accepted friends                                 |
+| `platform`        | `PlatformApi`                  | The calling player's platform-currency balances and earn allowance    |
+| `profiles`        | `ProfilesApi`                  | Another player's per-game profile                                     |
+| `client`          | `GemClient`                    | The platform API by path, for what the members above do not cover     |
+
+```ts
+interface FunctionContext {
+  readonly gameId: string;
+  readonly channel: 'dev' | 'test' | 'release';
+  readonly invocationId: string; // the id `gemctl function invoke` reports
+  readonly caller:
+    | { readonly type: 'player'; readonly playerId: string }
+    | { readonly type: 'game-server'; readonly serverId: string | null };
+}
+```
+
+`gem.identity` is the same three fields a browser game reads from its own `gem.identity`, so code
+that keys records on `playerId` runs unchanged. The entry also exports the error classes a game
+already catches (`GemApiError`, `AuthError`, `TransportRefusal`, `GemSaveError` and
+`FriendChallengeError`), so an `instanceof` check reads the same in both places. The
+[function API reference](api/api-reference-function.md) documents each member above, and the
+methods, types and errors behind all of them but `characters`, `transfers` and `client`.
 
 What a browser game has that is backed by the page or the arcade (ads, purchases, rooms, device
 settings, sharing) is not on `gem` inside a function. Four more differences, each following from
@@ -149,20 +214,29 @@ events may be lost.
 ## 4. Check before you upload
 
 ```bash
-gemctl function check dist/function.js
+gemctl function check functions/score-check/dist/function.js
 ```
 
 `check` runs the platform's publish-time validation for JavaScript on your machine, and an upload
-answers `400 source_invalid` with the same `details.reason`:
+runs it first and answers `400 source_invalid` with the same `details.reason`:
 
-| Reason             | What it usually is                                                        | What to change                                    |
-| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------- |
-| `not_a_module`     | A parse error, with its line and column, or a file that is not UTF-8      | Fix the syntax; bundle to ES2022                  |
-| `forbidden_import` | An `import` or `export … from` of anything but the SDK, or an `import()`  | Bundle the dependency in; drop the dynamic import |
-| `missing_handle`   | Neither `handle` nor `handleJson` is exported (`export *` does not count) | Export one of them from the module itself         |
-| `ambiguous_handle` | Both are exported                                                         | Keep one                                          |
-| `too_large`        | Over the size limit, the same one a component has                         | Bundle less; check what your build pulled in      |
+| Reason             | What it usually is                                                                          | What to change                                    |
+| ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `not_a_module`     | A parse error, with its line and column, or a file that is not UTF-8                        | Fix the syntax; bundle to ES2022                  |
+| `forbidden_import` | Any `import` or `export … from`, or an `import()`                                           | Bundle all of it in, the SDK too; drop `import()` |
+| `missing_handle`   | Neither `handle` nor `handleJson` is a named export (`export *` and `default` do not count) | Export one of them from the module itself         |
+| `ambiguous_handle` | Both are exported                                                                           | Keep one                                          |
+| `too_large`        | Over the size limit, the same one a component has                                           | Bundle less; check what your build pulled in      |
 
 An upload also answers `source_invalid`, rather than `component_invalid`, for `not_uploaded`,
-`size_mismatch` and `sha256_mismatch`: upload again. Promoting, channels and invoking are the same
-as for a component (serverless-functions.md sections 4 to 7).
+`size_mismatch` and `sha256_mismatch`: upload again. gemctl uploads a `.js` or `.mjs` file as
+JavaScript; it does not accept TypeScript, so upload what your build wrote.
+
+## 5. Publishing
+
+Uploading, promoting, rolling back and channels are the same as for a component
+(serverless-functions.md sections 4 and 5). On the website, the **Functions** tab of your game's
+**Builds** page promotes a version to a channel, rolls back by promoting an earlier one, and shows
+each channel's calls and daily usage and the last 24 hours of `dev` logs; a JavaScript version is
+marked there as running as JavaScript. Uploading is gemctl's alone. Invoking a function from your
+game or the terminal is serverless-functions.md sections 6 and 7.

package/docs/serverless-functions.md

@@ -55,8 +55,10 @@ possible.
 
 ## 2. What a function is
 
-A function is one WebAssembly **component** per game per channel, built against the platform's
-`gem:functions` world. It exports exactly one function:
+A function is one WebAssembly **component** or one JavaScript module per game per channel. A
+JavaScript module is written against the SDK instead, and
+[serverless-functions-js.md](serverless-functions-js.md) covers what differs for one. A component
+is built against the platform's `gem:functions` world, and exports exactly one function:
 
 ```wit
 export handle: func(input: list<u8>) -> result<list<u8>, string>;
@@ -450,12 +452,13 @@ reason to move the work to a game server.
 | ------------------------------------------------------------------------------ | -------------------------------------- |
 | Wall clock                                                                     | 5 seconds                              |
 | CPU                                                                            | 1 second of that 5                     |
-| Memory                                                                         | 64 MiB                                 |
+| Memory                                                                         | 256 MiB                                |
 | `call-api`, `download-link` and `upload-link` calls                            | 32, all three together                 |
 | A value handed to one `log`, `call-api`, `download-link` or `upload-link` call | 16 MiB                                 |
 | Input                                                                          | 256 KiB                                |
 | Output                                                                         | 1 MiB                                  |
-| Component size                                                                 | 32 MiB                                 |
+| Lines your function logs, kept per call (`dev` only)                           | 100 lines or 64 KiB, whichever first   |
+| Component or JavaScript module size                                            | 32 MiB                                 |
 | Calls, per caller per minute                                                   | 30 for a player, 120 for a game server |
 
 **The per-minute budget belongs to the caller, not to your game.** A player who spends theirs is
@@ -464,8 +467,9 @@ decision point, such as the end of a run or a claim, and never on a timer or onc
 
 ## 3. Writing one
 
-The reference toolchain is Rust. gemctl writes the starter crate and wraps what your build
-produces, and the build in between is yours:
+The reference toolchain for a component is Rust; to write a function in JavaScript or TypeScript,
+see [serverless-functions-js.md](serverless-functions-js.md). gemctl writes the starter crate and
+wraps what your build produces, and the build in between is yours:
 
 ```bash
 gemctl function init functions/score-check
@@ -618,6 +622,15 @@ been purged yet.
 `gemctl function delete <version> --yes` is refused while any channel serves the version, and
 gemctl cannot undo it.
 
+**The website does the same from the Functions tab of your game's Builds page.** It lists every
+version with its description, size, SHA-256 and the channels serving it, and promotes, unassigns and
+deletes, asking you to confirm before it promotes to `release`. Rolling back there is the same act:
+promote the earlier version. It cannot upload; that is `gemctl function upload`. The tab also shows
+each channel's calls today and its daily usage over the last 7, 28 or 90 days (calls, unsuccessful
+calls, CPU time, the longest call and peak memory), and the last 24 hours of `dev` logs, filtered by
+time, level, outcome or invocation id. Promoting, unassigning and deleting there take an Owner,
+Admin or Contributor role on the game; anyone else on the team can only look.
+
 ## 5. Channels
 
 Each channel (`dev`, `test` and `release`) serves at most one function version. A call never names
@@ -674,7 +687,8 @@ it is the progression's own state, or a key the platform decides (section 2).
 platform's code from section 8, and the error adds what that code needs:
 
 - `err.functionMessage` is the text your `handle` returned in `Err`, on `function_error`. Your
-  function wrote it and it may repeat what the caller sent, so log it and never render it as markup;
+  function wrote it and it may repeat what the caller sent, so log it and never render it as markup.
+  For a JavaScript function it is the thrown exception's `name: message`;
 - `err.failure` says which limit or fault ended the call, on `function_failed`;
 - `err.retryable` is decided by the code. It is `false` for `function_timeout`, because the same
   input runs out of time again, and for `functions_not_configured`, because functions are switched
@@ -777,9 +791,10 @@ or `game_server`:
   exceeded. The platform writes it and never copies your function's data into it.
 
 Newest first means a call's closing line comes before what it logged. **A call's logging is
-capped**: once it reaches its per-call log limit, that `log` call and every later one go
-unrecorded, and the closing line's `dropped_log_lines` says how many. A log that stops part-way
-with a nonzero count means your function logged too much, not that it went quiet.
+capped**: once it reaches 100 lines or 64 KiB of logged text, whichever comes first, that `log`
+call and every later one go unrecorded, and the closing line's `dropped_log_lines` says how many.
+A log that stops part-way with a nonzero count means your function logged too much, not that it
+went quiet.
 
 `--invocation-id`, `--level` (`debug`, `info`, `warn` or `error`) and `--outcome` narrow the page.
 `--level` picks what your function logged and `--outcome` picks closing lines, so the two cannot be
@@ -804,7 +819,7 @@ the last column: it is `true` exactly where this table says to retry.
 
 | What you get                                               | What happened                                                                                                                                       | What to do                                                             |
 | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `422 function_error`                                       | Your `handle` returned `Err`. The text is `err.functionMessage`                                                                                     | Fix your code or the input. Return verdicts in `Ok`                    |
+| `422 function_error`                                       | Your `handle` returned `Err`, or your JavaScript function threw. The text is `err.functionMessage`                                                  | Fix your code or the input. Return verdicts in `Ok`                    |
 | `422 function_failed`                                      | It did not finish. `err.failure` is `trap`, `memory_exceeded`, `cpu_budget_exceeded`, `host_call_limit`, `output_too_large` or `argument_too_large` | A bug or a limit in the function. Reproduce with the same input        |
 | `504 function_timeout`                                     | It ran past the wall clock                                                                                                                          | Do not retry: the same input takes as long again                       |
 | `404 function_not_published`                               | Nothing is promoted on the caller's channel                                                                                                         | `gemctl function promote <version> --channel <channel>`                |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "11.1.2",
+  "version": "12.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -1514,6 +1514,90 @@
       },
       "rateLimit": { "perMinute": 30 }
     },
+    {
+      "type": "gem.ticketEvent",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "A matchmaking ticket this player is on changed state. Gated by the",
+        "`ticketEvents` capability; the mapping lives in schema/capabilities.json",
+        "and nowhere else.",
+        "",
+        "gem-api's `matchmaking_ticket_queued`, `_matched`, `_expired`,",
+        "`_cancelled` and `_failed`, which it sends to EVERY player a ticket",
+        "seats: its owner and, for a party's ticket, every member. A party",
+        "queues as one ticket and it is the leader's, so a member's frame is on a",
+        "ticket it never created and cannot read — only the owner may. This is",
+        "the only thing that can tell that frame its party is queued, and how",
+        "the wait ended.",
+        "",
+        "A HINT, LIKE EVERY RELAY, and for a member a hint with nothing behind",
+        "it to re-read. So the frame gives it exactly the authority of a",
+        "display: a member's view of the ticket can be shown and cannot be",
+        "cancelled or kept alive, and nothing is entered on the strength of it.",
+        "A `matched` makes the frame look for the seat over its OWN token, which",
+        "is where a room is believed. For the ticket's OWNER the event is a cue",
+        "to ask the platform at once, exactly as a relayed match start is.",
+        "",
+        "ITS OWN TYPE, for the reason gem.seatedEvent gives: an unknown TYPE is",
+        "ignored by any frame, and the capability keeps the parent from sending",
+        "it to a frame that would not understand it.",
+        "",
+        "NOTHING ABOUT ANYBODY CROSSES. The push names no player and no other",
+        "ticket, and neither does this. The templates gem-api lists on `queued`",
+        "stop at the parent: the frame's game chose them, or its leader's did.",
+        "",
+        "`event` IS CLOSED, and it is the ticket's status. A status gem-api adds",
+        "later is not relayed until this enum names it — the parent drops what",
+        "it cannot name rather than send a value the frame would refuse.",
+        "",
+        "PARENT TO FRAME ONLY. A frame-authored ticket event would let a game",
+        "tell the parent, and through it nobody, that a queue it does not own",
+        "moved."
+      ],
+      "fields": {
+        "event": {
+          "kind": "enum",
+          "values": ["queued", "matched", "expired", "cancelled", "failed"],
+          "$comment": "The ticket's status after the change. `queued` is its creation; every other value is final."
+        },
+        "ticketId": { "kind": "string", "maxLength": 64 },
+        "partySize": {
+          "kind": "int",
+          "min": 1,
+          "max": 64,
+          "optional": true,
+          "$comment": "How many players the ticket seats. Sent with `queued`."
+        },
+        "queuedAt": {
+          "kind": "int",
+          "min": 0,
+          "max": 4102444800,
+          "optional": true,
+          "$comment": "When the ticket was queued, in Unix seconds. Sent with `queued`."
+        },
+        "expiresAt": {
+          "kind": "int",
+          "min": 0,
+          "max": 4102444800,
+          "optional": true,
+          "$comment": "When the ticket gives up if it is still waiting, in Unix seconds. Sent with `queued`. A frame that has seen no ending once this long has passed stops showing the ticket as waiting: the pushes are not retried, and a member has no other way to learn the ticket is over."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "Why a ticket ended without a match: `timed_out`, `heartbeat_lapsed`, `requested`, `party_changed`, `handoff_failed`. Open, so a reason added later reaches the game."
+        },
+        "roomId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "The room a `matched` ticket's players were seated in. A place to look, not a seat: the frame reads the room over its own token and checks this player is a member."
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
 
     {
       "type": "gem.signalEvent",

package/schema/capabilities.public.json

@@ -93,6 +93,12 @@
         "gem.autoStartFailedEvent"
       ]
     },
+    "ticketEvents": {
+      "implemented": true,
+      "gates": [
+        "gem.ticketEvent"
+      ]
+    },
     "partySeating": {
       "implemented": true,
       "gates": [