@genex-ai/multiplayer 0.16.1 → 0.16.2

package/README.md

@@ -263,10 +263,20 @@ can't starve it and a chat flood can't starve movement.
 ## `voice` — mesh voice chat
 
 ```ts
+import { getShell } from '@genex-ai/embed-sdk';   // 0.32.0+
+
+// Voice is not available inside the Genex app yet — do not draw the button there.
+joinBtn.hidden = getShell() === 'app';
+
 // MUST be inside a click/tap handler — browsers gate the mic prompt AND playback on a gesture.
 joinBtn.onclick = async () => {
-  try { await room.voice.join(); }            // rejects if the player denies the microphone
-  catch (err) { showNotice('Microphone needed for voice'); }
+  try { await room.voice.join(); }
+  catch (err) {
+    // The page around the game withheld the microphone and the player was never asked:
+    // this build did not declare it (see below). Nothing the player can allow.
+    if ((err as Error).name === 'VoiceNotDelegatedError') showNotice('Voice chat is not available here');
+    else showNotice('Microphone needed for voice');   // the player said no, or has no microphone
+  }
 };
 
 room.on('voice', (participants) => renderVoiceHud(participants));  // joined/left/speaking/connected
@@ -277,6 +287,36 @@ room.voice.mute(playerId);            // local only
 room.voice.leave();                   // releases the mic (turns the recording indicator off)
 ```
 
+**The microphone is declared per build.** On its Genex page a game runs in a frame, and the
+page gives that frame a microphone only when the build said it needs one. A build that did
+not is refused at once, with no prompt — while the very same build works on the game's own
+link and on a dev server, which is why it is easy to ship without noticing. The declaration
+is made at `genex preview` and `genex publish` (CLI **1.36.6+**), which read the game's own
+source and declare the microphone when they find `.voice.join()` called with nothing or
+with an options object written at the call — on any `.voice`, so `mm.session.voice.join()`
+counts. Both print what the build is given on its Genex page, so a missing declaration
+shows before a player meets it. A call the CLI cannot see (`voice.join(opts)` with the
+options in a variable, `const { voice } = room; voice.join()`, or code outside the game's
+`src/`) is declared by hand, in the game's `package.json`:
+
+```jsonc
+"genex": {
+  "capabilities": ["microphone"]
+}
+```
+
+The declaration belongs to the build, so preview or publish again after adding it. The
+spatial pack (`npx genex controller voice`) declares the microphone by itself.
+
+The refusal names itself: since **0.16.2**, `join()` rejects with an error whose `name` is
+`VoiceNotDelegatedError` when it was the page, not the player, that said no (the browser's
+own error is its `cause`). Chromium browsers can make that distinction; in the others the
+page's refusal arrives as the browser's own error, the same as a player's.
+
+**Not in the Genex app yet.** Inside the Genex mobile app the microphone is refused for
+every game, declared or not, and `join()` rejects as if the player had said no. Hide the
+voice button there, as above.
+
 **Party-sized, not room-sized — max 6.** Audio goes peer-to-peer in a full mesh: everyone
 uploads to everyone. The relay carries no audio at all, only the roster and the WebRTC
 handshake. Past a small party what breaks first is not bandwidth but reliability — a joiner
@@ -429,17 +469,51 @@ For `preset: 'private'` games, skip the queue: a host mints an invite **code**,
 
 ```ts
 import { createPrivate, joinPrivate } from "@genex-ai/multiplayer";
+import { share, getEntry } from "@genex-ai/embed-sdk";   // 0.32.0+
+
+const opts = { urls, room: slug, auth: () => getColyseusAuth() };
 
 // host
-const lobby = await createPrivate<State>({ urls, room: slug, auth: () => getColyseusAuth() });
-share(lobby.code);                 // e.g. show it in the UI
+const lobby = await createPrivate<State>(opts);
+showCode(lobby.code);              // show the code as well: the way in when a link will not do
+
+// host's Invite button. share() has to start inside the click, before any await.
+inviteBtn.onclick = async () => {
+  const { status, url } = await share({ text: "Join my lobby", params: { lobby: lobby.code } });
+  if (status === "copied") toast("Invite link copied");
+  if (status === "unavailable") showLink(url);   // no share sheet and no clipboard: show the link
+};
 
-// friend (elsewhere)
-const joined = await joinPrivate<State>(code, { urls, room: slug, auth: () => getColyseusAuth() });
+// friend: one way in, for the code from a link and for a code typed by hand
+async function enter(code: string) {
+  if (!/^[\w-]{1,32}$/.test(code)) return null;   // anyone can write a link: take a code, nothing else
+  try {
+    return await joinPrivate<State>(code, opts);
+  } catch {
+    showNotice("That lobby is no longer open");   // closed, or out of this player's reach
+    return null;
+  }
+}
+
+// at boot, after waitForPlayer(): were they sent an invite link?
+const invited = getEntry().params.get("lobby");
+const joined = invited ? await enter(invited) : null;   // null: the menu, with its "Enter code" field
 
 // then identical to matchmake(): .session, .matchmaking, eliminated()/score()/finish(), cancel()
 ```
 
+`share()` builds the link itself: the game's page on Genex plus `?lobby=<code>` (on a
+creator's own domain, that address). `getEntry()` gives the parameter back to whoever opens
+it, on the game page, on the game's own link and across the sign-in round trip. Do not
+build the link from `location.href`: inside the game page that is the frame's bare address,
+not the page a friend should land on. Any parameter name works except the platform's own
+(`embed`, `ref`, `s`, `from`, `remix`, `slug`, and everything starting `genex_`).
+
+`joinPrivate` rejects when the code does not lead to a lobby this player can reach: it has
+closed, or its host is on another region's relay than this player's nearest one. Catch it
+and show the menu. Keep the typed code as the second way in: a shell that does not pass the
+link's parameter on yet opens the game without it.
+
 ## Rules of thumb
 
 - **`me` / `shared` are synced; everything else is local.** Movement input → mutate a local object → `me.set` it on the tick.

package/dist/index.js

@@ -33,6 +33,13 @@ function createIceRequester(send, timeoutMs) {
 }
 
 // src/voice.ts
+var NOT_DELEGATED = "The microphone was refused by the page that frames this game, not by the player: the frame was not given it, so the browser never asked. On its Genex page a build is given the microphone only when it declares it. An up-to-date genex CLI declares it at `genex preview` and `genex publish` when the game's own source calls voice.join(); to declare it by hand, add \"microphone\" to genex.capabilities in the game's package.json. Then preview or publish again.";
+var VoiceNotDelegatedError = class extends Error {
+  constructor(cause) {
+    super(NOT_DELEGATED, { cause });
+    this.name = "VoiceNotDelegatedError";
+  }
+};
 var DEFAULT_ICE = [{ urls: "stun:stun.l.google.com:19302" }];
 var SPEAKING_POLL_MS = 120;
 var DEFAULT_SPEAKING_THRESHOLD = 0.02;
@@ -87,8 +94,10 @@ var VoiceMesh = class {
     return () => this.listeners.delete(cb);
   }
   /** Acquire the microphone. Throws if the user denies it or no device exists — the caller
-   *  surfaces that; it is a normal outcome, not a bug. Must be called from a user gesture:
-   *  browsers gate both the permission prompt and audio playback on one. */
+   *  surfaces that; it is a normal outcome, not a bug. The one refusal that IS a bug throws a
+   *  VoiceNotDelegatedError instead: the page framing the game withheld the microphone, because
+   *  the build never declared it. Must be called from a user gesture: browsers gate both the
+   *  permission prompt and audio playback on one. */
   async start(options = {}, holdPeering = false) {
     if (this.running) return;
     this.peeringHeld = holdPeering;
@@ -96,10 +105,14 @@ var VoiceMesh = class {
     this.spatial = options.spatial === true;
     this.threshold = options.speakingThreshold ?? DEFAULT_SPEAKING_THRESHOLD;
     this.micOn = options.startMuted !== true;
-    this.local = await navigator.mediaDevices.getUserMedia({
-      audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },
-      video: false
-    });
+    try {
+      this.local = await navigator.mediaDevices.getUserMedia({
+        audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },
+        video: false
+      });
+    } catch (err) {
+      throw micRefusal(err);
+    }
     for (const t of this.local.getAudioTracks()) t.enabled = this.micOn;
     this.audio = new AudioContext();
     this.localAnalyser = this.makeAnalyser(this.local);
@@ -360,6 +373,24 @@ var VoiceMesh = class {
     }
   }
 };
+function isFramed() {
+  try {
+    return window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
+function micRefusal(err) {
+  if (err?.name !== "NotAllowedError") return err;
+  try {
+    if (!isFramed()) return err;
+    const policy = document.featurePolicy;
+    if (policy?.allowsFeature?.("microphone") !== false) return err;
+  } catch {
+    return err;
+  }
+  return new VoiceNotDelegatedError(err);
+}
 function hasTurnUrl(server) {
   const urls = Array.isArray(server.urls) ? server.urls : [server.urls];
   return urls.some((u) => typeof u === "string" && u.startsWith("turn"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/multiplayer",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",