@powly/sdk 0.6.0 → 0.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 The SDK for games on [Powly](https://powly.gg): the launch handshake with Powly, the player's
 profile, session tokens and the platform services (saves, leaderboards, achievements, friends,
-invites, multiplayer rooms, Twitch chat).
+invites, multiplayer rooms, Twitch chat, sound settings).
 
 ## Install
 
@@ -31,7 +31,7 @@ await powly.leaderboards.submit("high-score", 1200);
 Without a bundler, load the classic script instead; it defines `window.Powly`:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@powly/sdk@0.6.0/dist/powly.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@powly/sdk@0.8.0/dist/powly.js"></script>
 ```
 
 ## Testing
@@ -58,7 +58,7 @@ your backend verifies session tokens or exchanges them for an access token.
 ## This repository
 
 The SDK is developed in Powly's main repository and mirrored here with each release; this is
-`@powly/sdk` 0.6.0. Issues are welcome; changes land through the main repository.
+`@powly/sdk` 0.8.0. Issues are welcome; changes land through the main repository.
 
 To build it yourself (Node.js 24 or newer):
 

package/dist/powly.d.ts

@@ -1,6 +1,6 @@
-/* Powly SDK 0.6.0: types for powly.js and powly.mjs */
+/* Powly SDK 0.8.0: types for powly.js and powly.mjs */
 /** This SDK's version; Powly's Studio shows it next to the downloads. */
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.8.0";
 
 export declare const PROTOCOL = "powly-sdk";
 export declare const PROTOCOL_VERSION = 1;
@@ -8,6 +8,44 @@ export declare const PROTOCOL_VERSION = 1;
 export declare const OPTIONS_BUTTON_CORNERS: readonly ["top-left", "top-right", "bottom-left", "bottom-right"];
 export type OptionsButtonCorner = (typeof OPTIONS_BUTTON_CORNERS)[number];
 export declare const isOptionsButtonCorner: (value: unknown) => value is OptionsButtonCorner;
+/**
+ * A kind of sound the game has (music, drawing sounds…), which Powly's sound menu shows with a
+ * volume slider (`volume`, default true), an on/off switch (`toggle`, default true), or both.
+ */
+export type AudioChannel = {
+    id: string;
+    label: string;
+    volume?: boolean;
+    toggle?: boolean;
+};
+/** One channel's setting: its volume, 0 to 1, and whether it's on. */
+export type ChannelState = {
+    volume: number;
+    on: boolean;
+};
+/** Channel ids: letters, digits, _ and -, starting with a letter, up to 32. */
+export declare const AUDIO_CHANNEL_ID: RegExp;
+export declare const MAX_AUDIO_CHANNELS = 8;
+export declare const MAX_AUDIO_LABEL = 32;
+/**
+ * The player's sound settings from Powly's sound menu. `volume` (0 to 1) is the player's overall
+ * volume, `channels` the game's own (by channel id); `muted` silences everything.
+ */
+export type AudioState = {
+    volume: number;
+    muted: boolean;
+    channels: Record<string, ChannelState>;
+};
+/** The channels a game sent, cleaned up: valid ids, short labels, no repeats, at most 8. */
+export declare function audioChannelsOf(value: unknown): AudioChannel[];
+/** What a game changes from its own sound menu; channels by id, only the fields given. */
+export type AudioChanges = {
+    volume?: number;
+    muted?: boolean;
+    channels?: Record<string, Partial<ChannelState>>;
+};
+/** A volume between 0 and 1, or null. */
+export declare const volumeOf: (value: unknown) => number | null;
 export type InitMessage = {
     protocol: typeof PROTOCOL;
     version: number;
@@ -23,6 +61,13 @@ export type InitMessage = {
      * player's own choice wins. Left out: Powly's default (top left).
      */
     optionsButton?: OptionsButtonCorner;
+    /**
+     * The SDK follows Powly's sound menu (SDK 0.8.0 and later): `channels` are the game's own
+     * volume controls, shown as sliders. Older SDKs leave it out.
+     */
+    audio?: {
+        channels: AudioChannel[];
+    };
 };
 export type PlayerProfile = {
     /** This player's ID in this game: stable, and different in every game. */
@@ -49,12 +94,19 @@ export type ReadyMessage = {
     pac?: {
         guard: boolean;
     };
+    /** The player's sound settings when the game starts. Missing from older Powly hosts. */
+    audio?: AudioState;
 };
 export type FailedMessage = {
     type: "failed";
     error: string;
 };
-export type HostMethod = "getSessionToken" | "purchases.open" | "fullscreen.toggle" | "invites.open" | "quit";
+/** What a game may ask the Powly page for. */
+export declare const HOST_METHODS: readonly ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open", "players.open", "twitch.connect", "audio.set", "audio.channels", "quit"];
+export type HostMethod = (typeof HOST_METHODS)[number];
+/** "players.open": what Powly's player dialog opens on. */
+export declare const PLAYER_VIEWS: readonly ["profile", "report"];
+export type PlayerView = (typeof PLAYER_VIEWS)[number];
 export type RequestMessage = {
     type: "request";
     id: number;
@@ -66,11 +118,33 @@ export type RequestMessage = {
      * dialog shows them as in the party, without an Invite button.
      */
     members?: string[];
+    /** "players.open": the player (their player ID in this game) to show. */
+    playerId?: string;
+    /** "players.open": open on the profile (the default) or straight on reporting them. */
+    view?: PlayerView;
+    /** "audio.set": what the game's own sound menu changed. */
+    audio?: AudioChanges;
+    /** "audio.channels": every channel the game has now (registered later than init). */
+    channels?: AudioChannel[];
 };
 /** What "invites.open" answers once Powly's dialog closed: the friends the player invited. */
 export type InvitesOpenResult = {
     invited: string[];
 };
+/**
+ * What "players.open" answers once Powly's player dialog closed: whether the player has that
+ * player blocked now (the game may hide their chat, say). Whether they reported them stays private.
+ */
+export type PlayersOpenResult = {
+    blocked: boolean;
+};
+/**
+ * What "twitch.connect" answers once Powly's Connect Twitch dialog closed: whether the player's
+ * Twitch is connected now (the SDK then reads GET /twitch again).
+ */
+export type TwitchConnectResult = {
+    connected: boolean;
+};
 export type ResponseMessage = {
     type: "response";
     id: number;
@@ -90,9 +164,20 @@ export type HostEventName = "shown" | "pause" | "resume" | "ended";
 export type EventMessage = {
     type: "event";
     event: HostEventName;
+}
+/** The player changed the sound settings (Powly's sound menu, or its M key). */
+ | {
+    type: "event";
+    event: "audio";
+    audio: AudioState;
 };
 export type HostMessage = ReadyMessage | FailedMessage | ResponseMessage | EventMessage;
 export declare const isInitMessage: (data: unknown) => data is InitMessage;
+/** A request with a method this Powly doesn't know (from a newer SDK): answered with an error. */
+export declare const isRequestShaped: (data: unknown) => data is {
+    type: "request";
+    id: number;
+};
 export declare const isRequestMessage: (data: unknown) => data is RequestMessage;
 
 export declare const POWLY_ORIGINS: readonly string[];
@@ -481,14 +566,21 @@ type Events = {
     };
     state: TwitchChatState;
 };
+export type ConnectOptions = {
+    /** Ask the player to connect Twitch in Powly's dialog when they haven't. Default false. */
+    prompt?: boolean;
+};
 export type TwitchApi = {
     /** The game's setting and the player's channel, without opening chat. */
     info(): Promise<TwitchInfo>;
     /**
      * Opens the player's chat when they have a channel to read (`status: "connected"`). Resolves
      * with the info, once chat is joined (or failed to; it keeps retrying in the background).
+     * `prompt`: when the player hasn't connected Twitch, Powly first asks them to in its own dialog
+     * (they can connect it there without leaving the game); `status` is still "not_connected" if
+     * they closed it.
      */
-    connect(): Promise<TwitchInfo>;
+    connect(options?: ConnectOptions): Promise<TwitchInfo>;
     /** Closes chat; `connect()` opens it again. */
     disconnect(): void;
     readonly state: TwitchChatState;
@@ -509,6 +601,8 @@ export declare function parseIrcLine(line: string): IrcMessage | null;
 export declare function chatMessageOf(message: IrcMessage): TwitchChatMessage | null;
 export declare function createTwitch(options: {
     getInfo: () => Promise<TwitchInfo>;
+    /** Opens Powly's Connect Twitch dialog; resolves with whether Twitch is connected now. */
+    prompt?: () => Promise<boolean>;
     /** Twitch chat's WebSocket URL (tests point it elsewhere). */
     url?: string;
 }): TwitchApi & {
@@ -516,6 +610,58 @@ export declare function createTwitch(options: {
 };
 
 
+export type AudioOptions = {
+    /**
+     * The game's kinds of sound, shown in Powly's sound menu (up to 8): `{ id, label }`, with a
+     * volume slider (`volume: false` leaves it out) and an on/off switch (`toggle: false`).
+     */
+    channels?: AudioChannel[];
+    /**
+     * Apply the overall volume and mute to the page's sound by itself. Default true; turn it off
+     * when the game applies `level()` to everything itself.
+     */
+    auto?: boolean;
+};
+export type AudioApi = {
+    /** The player's overall volume, 0 to 1. */
+    readonly volume: number;
+    /** Everything silenced (Powly's mute, or its M key). */
+    readonly muted: boolean;
+    /** The game's channels by id: their volume (0 to 1) and whether they're on. */
+    readonly channels: Record<string, ChannelState>;
+    /**
+     * What to play at, 0 to 1: a channel's volume (0 while it's off), or (no channel) full volume.
+     * With `auto` off, the overall volume and mute are in it too.
+     */
+    level(channel?: string): number;
+    /**
+     * Adds a channel to Powly's sound menu after init (or changes its label or controls), e.g.
+     * once a mode with its own sounds starts. Up to 8 channels.
+     */
+    register(channel: AudioChannel): Promise<void>;
+    /**
+     * Changes the settings from the game's own sound menu, so Powly's stays the same:
+     * `{ volume, muted, channels: { music: { volume: 0.5 }, drawing: { on: false } } }`. Unknown
+     * channels are ignored.
+     */
+    set(changes: AudioChanges): Promise<void>;
+    /** The settings changed (in Powly's sound menu, or with `set`). */
+    on(event: "change", listener: (audio: AudioState) => void): () => void;
+};
+/** Volume of the page's sound overall: 0 when muted. */
+export declare const masterLevel: (state: AudioState) => number;
+/**
+ * Puts a volume control in front of the page's speakers: Web Audio connections to a real-time
+ * AudioContext's destination go through a gain node per context, and media elements' volume is
+ * scaled (the volume the game set still reads back unchanged; elements played through Web Audio
+ * are left to the gain node). Returns how to set it.
+ */
+export declare function installMasterGain(win?: Window & typeof globalThis): {
+    set(level: number): void;
+};
+
+
+
 
 
 
@@ -536,6 +682,12 @@ export type InitOptions = {
      * UI leaves free. Players can still move it, and their choice wins.
      */
     optionsButton?: OptionsButtonCorner;
+    /**
+     * Powly's sound menu (src/audio.ts): the game's own volume `channels` (sliders next to the
+     * player's overall volume), and whether the SDK applies the overall volume and mute to the
+     * page's sound itself (`auto`, default true).
+     */
+    audio?: AudioOptions;
 };
 export type LeaderboardEntry = {
     rank: number;
@@ -607,6 +759,25 @@ export type PowlySession = {
             invited: string[];
         }>;
     };
+    /**
+     * Other players of this game, by their player ID (from rooms, leaderboards, friends…).
+     * `open` shows Powly's own dialog over the game (drawn by Powly, not the game) with their
+     * profile, where the player can add them as a friend, block or report them; with
+     * `{ view: "report" }` it opens straight on reporting them. Games can't file reports
+     * themselves: the player always confirms in Powly's dialog. Resolves when it closes, with
+     * whether the player has them blocked now (hide their chat, say). Fails for player IDs that
+     * aren't from this game.
+     */
+    players: {
+        open(playerId: string, options?: {
+            view?: PlayerView;
+        }): Promise<PlayersOpenResult>;
+    };
+    /**
+     * The player's sound settings from Powly's options bar: overall volume, mute and the game's
+     * channels (`Powly.init({ audio: { channels } })`). Play each channel at `level(channel)`.
+     */
+    audio: AudioApi;
     /** Realtime rooms (parties) with other players of this game. */
     rooms: RoomsApi;
     /**

package/dist/powly.js

@@ -1,8 +1,8 @@
-/* Powly SDK 0.6.0: defines window.Powly */
+/* Powly SDK 0.8.0: defines window.Powly */
 (function () {
 "use strict";
 /** This SDK's version; Powly's Studio shows it next to the downloads. */
-const SDK_VERSION = "0.6.0";
+const SDK_VERSION = "0.8.0";
 
 // The messages between a game (this SDK, inside Powly's iframe) and the Powly page that framed it.
 // Shared with the host side (apps/web/components/player/sdk-host.ts).
@@ -22,16 +22,61 @@ const OPTIONS_BUTTON_CORNERS = [
     "bottom-right",
 ];
 const isOptionsButtonCorner = (value) => OPTIONS_BUTTON_CORNERS.includes(value);
+/** Channel ids: letters, digits, _ and -, starting with a letter, up to 32. */
+const AUDIO_CHANNEL_ID = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+const MAX_AUDIO_CHANNELS = 8;
+const MAX_AUDIO_LABEL = 32;
+/** The channels a game sent, cleaned up: valid ids, short labels, no repeats, at most 8. */
+function audioChannelsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    const channels = [];
+    for (const entry of value) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { id, label, volume, toggle } = entry;
+        if (typeof id !== "string" || !AUDIO_CHANNEL_ID.test(id))
+            continue;
+        if (channels.some((channel) => channel.id === id))
+            continue;
+        const text = typeof label === "string" ? label.trim().slice(0, MAX_AUDIO_LABEL) : "";
+        const slider = volume !== false;
+        // Neither a slider nor a switch would show nothing: both, then.
+        const onOff = toggle !== false || !slider;
+        channels.push({ id, label: text || id, volume: slider, toggle: onOff });
+        if (channels.length === MAX_AUDIO_CHANNELS)
+            break;
+    }
+    return channels;
+}
+/** A volume between 0 and 1, or null. */
+const volumeOf = (value) => typeof value === "number" && Number.isFinite(value) ? Math.min(Math.max(value, 0), 1) : null;
+/** What a game may ask the Powly page for. */
+const HOST_METHODS = [
+    "getSessionToken",
+    "purchases.open",
+    "fullscreen.toggle",
+    "invites.open",
+    "players.open",
+    "twitch.connect",
+    "audio.set",
+    "audio.channels",
+    "quit",
+];
+/** "players.open": what Powly's player dialog opens on. */
+const PLAYER_VIEWS = ["profile", "report"];
 const isInitMessage = (data) => typeof data === "object" &&
     data !== null &&
     data.protocol === PROTOCOL &&
     data.type === "init" &&
     data.version === PROTOCOL_VERSION;
-const isRequestMessage = (data) => typeof data === "object" &&
+/** A request with a method this Powly doesn't know (from a newer SDK): answered with an error. */
+const isRequestShaped = (data) => typeof data === "object" &&
     data !== null &&
     data.type === "request" &&
-    Number.isInteger(data.id) &&
-    ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open", "quit"].includes(data.method);
+    Number.isInteger(data.id);
+const isRequestMessage = (data) => isRequestShaped(data) &&
+    HOST_METHODS.includes(data.method);
 
 // The Powly origins this build of the SDK trusts by default: a game only handshakes with a parent
 // page on one of them (unless it passes `powlyOrigin` to `Powly.init()` itself). Set at build
@@ -861,6 +906,11 @@ function createRooms(options) {
 //     });
 //   }
 //
+// A game with a Twitch mode among others (Twitch chat "optional" in Studio) passes
+// `{ prompt: true }` when the player picks that mode: if they haven't connected Twitch, Powly asks
+// them to in its own dialog (drawn by Powly, outside the game), and `connect()` resolves once
+// they did or closed it.
+//
 // Chat is Twitch IRC over a WebSocket (https://dev.twitch.tv/docs/chat/irc/). The connection comes
 // back by itself when it drops, and stops when the launch ends.
 const TWITCH_CHAT_URL = "wss://irc-ws.chat.twitch.tv:443";
@@ -1101,8 +1151,12 @@ function createTwitch(options) {
     };
     return {
         info: options.getInfo,
-        async connect() {
-            const info = await options.getInfo();
+        async connect(connectOptions = {}) {
+            let info = await options.getInfo();
+            if (info.status === "not_connected" && connectOptions.prompt && options.prompt) {
+                if (await options.prompt())
+                    info = await options.getInfo();
+            }
             const next = info.status === "connected" ? info.channel : null;
             if (!next || stopped) {
                 disconnect();
@@ -1141,6 +1195,154 @@ function createTwitch(options) {
     };
 }
 
+// Powly's sound menu for games (`powly.audio`): the player's overall volume, a mute (Powly's M
+// key), and the kinds of sound the game registers (channels: music, drawing sounds…), each with a
+// volume slider and an on/off switch, or one of them. The player sets them in Powly's options
+// bar; the game hears "change".
+//
+//   const powly = await Powly.init({
+//     audio: { channels: [{ id: "music", label: "Music" }] },
+//   });
+//   await powly.audio.register({ id: "drawing", label: "Drawing sounds", volume: false });
+//   music.volume = powly.audio.level("music");
+//   powly.audio.on("change", () => { music.volume = powly.audio.level("music"); });
+//   if (powly.audio.level("drawing") > 0) playScribble();
+//
+// The overall volume and mute apply by themselves (`auto`, on by default): the SDK puts a volume
+// control in front of the page's speakers, for Web Audio (every connection to an AudioContext's
+// destination goes through it) and for <audio>/<video> (their volume is scaled). So every game
+// on this SDK follows Powly's volume, and channels only need the channel's own value:
+// `level(channel)` is what to play at either way.
+/** Volume of the page's sound overall: 0 when muted. */
+const masterLevel = (state) => (state.muted ? 0 : state.volume);
+/** Live references to objects, for walking them later without keeping them alive. */
+function weakList() {
+    const seen = new WeakSet();
+    const refs = new Set();
+    return {
+        add(item) {
+            if (seen.has(item))
+                return false;
+            seen.add(item);
+            refs.add(new WeakRef(item));
+            return true;
+        },
+        has: (item) => seen.has(item),
+        *[Symbol.iterator]() {
+            for (const ref of refs) {
+                const item = ref.deref();
+                if (item)
+                    yield item;
+                else
+                    refs.delete(ref);
+            }
+        },
+    };
+}
+/**
+ * Puts a volume control in front of the page's speakers: Web Audio connections to a real-time
+ * AudioContext's destination go through a gain node per context, and media elements' volume is
+ * scaled (the volume the game set still reads back unchanged; elements played through Web Audio
+ * are left to the gain node). Returns how to set it.
+ */
+function installMasterGain(win = window) {
+    let level = 1;
+    // Web Audio.
+    const gainOf = new WeakMap();
+    const gains = weakList();
+    const Destination = win.AudioDestinationNode;
+    const Offline = win.OfflineAudioContext;
+    const nodeProto = win.AudioNode?.prototype;
+    const connect = nodeProto?.connect;
+    const disconnect = nodeProto?.disconnect;
+    /** The gain node standing in for `target` when it's a real-time context's destination. */
+    const standIn = (target) => {
+        if (!Destination || !(target instanceof Destination))
+            return null;
+        const context = target.context;
+        if (Offline && context instanceof Offline)
+            return null;
+        let gain = gainOf.get(context);
+        if (!gain) {
+            gain = context.createGain();
+            gain.gain.value = level;
+            gains.add(gain);
+            connect?.call(gain, target);
+            gainOf.set(context, gain);
+        }
+        return gain;
+    };
+    if (nodeProto && connect && disconnect) {
+        nodeProto.connect = function (target, ...rest) {
+            const gain = gains.has(this) ? null : standIn(target);
+            if (!gain)
+                return connect.call(this, target, ...rest);
+            connect.call(this, gain, ...rest);
+            // Chaining keeps working: connect() answers what it was given.
+            return target;
+        };
+        nodeProto.disconnect = function (...args) {
+            const gain = gains.has(this) ? null : standIn(args[0]);
+            return gain ? disconnect.call(this, gain, ...args.slice(1)) : disconnect.apply(this, args);
+        };
+    }
+    // Media elements: the volume the game set, and the one played (times `level`).
+    const media = win.HTMLMediaElement?.prototype;
+    const volume = media ? Object.getOwnPropertyDescriptor(media, "volume") : undefined;
+    const wanted = new WeakMap();
+    const elements = weakList();
+    const routed = new WeakSet();
+    const apply = (element) => {
+        const own = wanted.get(element) ?? 1;
+        volume?.set?.call(element, routed.has(element) ? own : own * level);
+    };
+    const track = (element) => {
+        if (!wanted.has(element))
+            wanted.set(element, volume?.get?.call(element) ?? 1);
+        elements.add(element);
+        apply(element);
+    };
+    if (media && volume?.get && volume.set) {
+        const { get, set } = volume;
+        Object.defineProperty(media, "volume", {
+            configurable: true,
+            enumerable: volume.enumerable,
+            get() {
+                return wanted.get(this) ?? get.call(this);
+            },
+            set(value) {
+                // Out of range throws, like the browser's own setter.
+                set.call(this, value);
+                wanted.set(this, value);
+                track(this);
+            },
+        });
+        const play = media.play;
+        media.play = function () {
+            track(this);
+            return play.call(this);
+        };
+    }
+    const createSource = win.AudioContext?.prototype.createMediaElementSource;
+    if (createSource) {
+        win.AudioContext.prototype.createMediaElementSource = function (element) {
+            routed.add(element);
+            track(element);
+            return createSource.call(this, element);
+        };
+    }
+    return {
+        set(next) {
+            level = next;
+            for (const gain of gains)
+                gain.gain.value = level;
+            for (const element of elements)
+                apply(element);
+        },
+    };
+}
+
+
 
 
 
@@ -1158,6 +1360,8 @@ function createTwitch(options) {
 //   const token = await powly.getSessionToken(); // send it to your backend, which verifies it
 //   const room = await powly.rooms.create();    // realtime parties (src/rooms.ts)
 //   await powly.twitch.connect();                // the streamer's Twitch chat (src/twitch.ts)
+//   await powly.players.open(playerId);          // Powly's profile dialog: add, block, report
+//   powly.audio.level("music");                  // Powly's sound menu (src/audio.ts)
 //
 // Nothing here is a security boundary: the game runs in the player's browser. Your backend must
 // verify session tokens (JWKS) or exchange them, and Powly checks everything server-side.
@@ -1202,6 +1406,12 @@ function init(options = {}) {
     if (origins.length === 0) {
         return Promise.reject(new PowlyError("This game only runs when launched from Powly."));
     }
+    const audioChannels = audioChannelsOf(options.audio?.channels ?? []);
+    // Before the game's engine makes a sound, so its connections go through the volume control.
+    const auto = options.audio?.auto !== false;
+    if (auto)
+        masterGain ??= installMasterGain();
+    const master = auto ? masterGain : null;
     return new Promise((resolve, reject) => {
         const channels = origins.map((origin) => {
             const channel = new MessageChannel();
@@ -1214,6 +1424,7 @@ function init(options = {}) {
                 ...(isOptionsButtonCorner(options.optionsButton) && {
                     optionsButton: options.optionsButton,
                 }),
+                audio: { channels: audioChannels },
             };
             channel.port1.onmessage = (event) => {
                 const data = event.data;
@@ -1222,7 +1433,7 @@ function init(options = {}) {
                     for (const other of channels)
                         if (other !== channel)
                             other.port1.close();
-                    resolve(createSession(channel.port1, data));
+                    resolve(createSession(channel.port1, data, { channels: audioChannels, master }));
                 }
                 else if (data?.type === "failed") {
                     clearTimeout(timer);
@@ -1240,7 +1451,22 @@ function init(options = {}) {
         }, options.timeoutMs ?? 10_000);
     });
 }
-function createSession(port, ready) {
+/** The page's volume control (src/audio.ts), put in once even if init runs again. */
+let masterGain = null;
+/** The sound settings Powly sent, with every channel (on, at full volume, when it sent none). */
+function audioStateOf(value, channels) {
+    const sent = (typeof value === "object" && value !== null ? value : {});
+    const levels = ((typeof sent.channels === "object" && sent.channels) || {});
+    return {
+        volume: volumeOf(sent.volume) ?? 1,
+        muted: sent.muted === true,
+        channels: Object.fromEntries(channels.map((channel) => {
+            const level = levels[channel.id];
+            return [channel.id, { volume: volumeOf(level?.volume) ?? 1, on: level?.on !== false }];
+        })),
+    };
+}
+function createSession(port, ready, sound) {
     let token = ready.token;
     let expiresAt = Date.now() + ready.expiresIn * 1000;
     let refreshing = null;
@@ -1249,6 +1475,23 @@ function createSession(port, ready) {
     const listeners = new Map();
     // "shown" comes once; games that listen for it later still hear it.
     let shown = false;
+    // The player's sound settings; the page's volume follows them (auto).
+    let channels = sound.channels;
+    let audio = audioStateOf(ready.audio, channels);
+    const audioListeners = new Set();
+    sound.master?.set(masterLevel(audio));
+    const setAudio = (next) => {
+        audio = next;
+        sound.master?.set(masterLevel(audio));
+        for (const listener of audioListeners) {
+            try {
+                listener(audio);
+            }
+            catch (error) {
+                console.error("[powly] an audio listener failed", error);
+            }
+        }
+    };
     port.onmessage = (event) => {
         const data = event.data;
         if (data?.type === "response") {
@@ -1262,7 +1505,13 @@ function createSession(port, ready) {
                 waiting.reject(new PowlyError(data.error));
         }
         else if (data?.type === "event") {
-            const name = data.event;
+            const message = data;
+            if (message.event === "audio") {
+                if ("audio" in message)
+                    setAudio(audioStateOf(message.audio, channels));
+                return;
+            }
+            const name = message.event;
             if (name === "shown") {
                 if (shown)
                     return;
@@ -1328,7 +1577,10 @@ function createSession(port, ready) {
         invite: sendInvite,
     });
     listeners.get("ended")?.add(() => realtime.stop());
-    const twitch = createTwitch({ getInfo: () => api("/twitch") });
+    const twitch = createTwitch({
+        getInfo: () => api("/twitch"),
+        prompt: async () => (await call("twitch.connect")).connected,
+    });
     listeners.get("ended")?.add(() => twitch.stop());
     const saves = {
         get: async (key) => {
@@ -1375,6 +1627,52 @@ function createSession(port, ready) {
                 return (await call("invites.open", { params, members }));
             },
         },
+        players: {
+            open: async (playerId, options = {}) => (await call("players.open", {
+                playerId,
+                ...(options.view && { view: options.view }),
+            })),
+        },
+        audio: {
+            get volume() {
+                return audio.volume;
+            },
+            get muted() {
+                return audio.muted;
+            },
+            get channels() {
+                return Object.fromEntries(Object.entries(audio.channels).map(([id, state]) => [id, { ...state }]));
+            },
+            level(channel) {
+                const state = channel === undefined ? undefined : audio.channels[channel];
+                const own = state ? (state.on ? state.volume : 0) : 1;
+                return sound.master ? own : own * masterLevel(audio);
+            },
+            async register(channel) {
+                const next = audioChannelsOf([
+                    ...channels.filter((existing) => existing.id !== channel?.id),
+                    channel,
+                ]);
+                if (!next.some((entry) => entry.id === channel?.id)) {
+                    throw new PowlyError(`A channel needs an id of letters, digits, _ and -, and a game has up to ${MAX_AUDIO_CHANNELS}.`);
+                }
+                // Same order as before; a changed channel keeps its place.
+                channels = [
+                    ...channels.map((existing) => next.find((entry) => entry.id === existing.id) ?? existing),
+                    ...next.filter((entry) => !channels.some((existing) => existing.id === entry.id)),
+                ];
+                const result = await call("audio.channels", { channels });
+                setAudio(audioStateOf(result, channels));
+            },
+            async set(changes) {
+                const result = await call("audio.set", { audio: changes });
+                setAudio(audioStateOf(result, channels));
+            },
+            on(_event, listener) {
+                audioListeners.add(listener);
+                return () => audioListeners.delete(listener);
+            },
+        },
         rooms: realtime.rooms,
         twitch: {
             info: twitch.info,

package/dist/powly.mjs

@@ -1,6 +1,6 @@
-/* Powly SDK 0.6.0: ES module */
+/* Powly SDK 0.8.0: ES module */
 /** This SDK's version; Powly's Studio shows it next to the downloads. */
-const SDK_VERSION = "0.6.0";
+const SDK_VERSION = "0.8.0";
 
 // The messages between a game (this SDK, inside Powly's iframe) and the Powly page that framed it.
 // Shared with the host side (apps/web/components/player/sdk-host.ts).
@@ -20,16 +20,61 @@ const OPTIONS_BUTTON_CORNERS = [
     "bottom-right",
 ];
 const isOptionsButtonCorner = (value) => OPTIONS_BUTTON_CORNERS.includes(value);
+/** Channel ids: letters, digits, _ and -, starting with a letter, up to 32. */
+const AUDIO_CHANNEL_ID = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+const MAX_AUDIO_CHANNELS = 8;
+const MAX_AUDIO_LABEL = 32;
+/** The channels a game sent, cleaned up: valid ids, short labels, no repeats, at most 8. */
+function audioChannelsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    const channels = [];
+    for (const entry of value) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { id, label, volume, toggle } = entry;
+        if (typeof id !== "string" || !AUDIO_CHANNEL_ID.test(id))
+            continue;
+        if (channels.some((channel) => channel.id === id))
+            continue;
+        const text = typeof label === "string" ? label.trim().slice(0, MAX_AUDIO_LABEL) : "";
+        const slider = volume !== false;
+        // Neither a slider nor a switch would show nothing: both, then.
+        const onOff = toggle !== false || !slider;
+        channels.push({ id, label: text || id, volume: slider, toggle: onOff });
+        if (channels.length === MAX_AUDIO_CHANNELS)
+            break;
+    }
+    return channels;
+}
+/** A volume between 0 and 1, or null. */
+const volumeOf = (value) => typeof value === "number" && Number.isFinite(value) ? Math.min(Math.max(value, 0), 1) : null;
+/** What a game may ask the Powly page for. */
+const HOST_METHODS = [
+    "getSessionToken",
+    "purchases.open",
+    "fullscreen.toggle",
+    "invites.open",
+    "players.open",
+    "twitch.connect",
+    "audio.set",
+    "audio.channels",
+    "quit",
+];
+/** "players.open": what Powly's player dialog opens on. */
+const PLAYER_VIEWS = ["profile", "report"];
 const isInitMessage = (data) => typeof data === "object" &&
     data !== null &&
     data.protocol === PROTOCOL &&
     data.type === "init" &&
     data.version === PROTOCOL_VERSION;
-const isRequestMessage = (data) => typeof data === "object" &&
+/** A request with a method this Powly doesn't know (from a newer SDK): answered with an error. */
+const isRequestShaped = (data) => typeof data === "object" &&
     data !== null &&
     data.type === "request" &&
-    Number.isInteger(data.id) &&
-    ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open", "quit"].includes(data.method);
+    Number.isInteger(data.id);
+const isRequestMessage = (data) => isRequestShaped(data) &&
+    HOST_METHODS.includes(data.method);
 
 // The Powly origins this build of the SDK trusts by default: a game only handshakes with a parent
 // page on one of them (unless it passes `powlyOrigin` to `Powly.init()` itself). Set at build
@@ -859,6 +904,11 @@ function createRooms(options) {
 //     });
 //   }
 //
+// A game with a Twitch mode among others (Twitch chat "optional" in Studio) passes
+// `{ prompt: true }` when the player picks that mode: if they haven't connected Twitch, Powly asks
+// them to in its own dialog (drawn by Powly, outside the game), and `connect()` resolves once
+// they did or closed it.
+//
 // Chat is Twitch IRC over a WebSocket (https://dev.twitch.tv/docs/chat/irc/). The connection comes
 // back by itself when it drops, and stops when the launch ends.
 const TWITCH_CHAT_URL = "wss://irc-ws.chat.twitch.tv:443";
@@ -1099,8 +1149,12 @@ function createTwitch(options) {
     };
     return {
         info: options.getInfo,
-        async connect() {
-            const info = await options.getInfo();
+        async connect(connectOptions = {}) {
+            let info = await options.getInfo();
+            if (info.status === "not_connected" && connectOptions.prompt && options.prompt) {
+                if (await options.prompt())
+                    info = await options.getInfo();
+            }
             const next = info.status === "connected" ? info.channel : null;
             if (!next || stopped) {
                 disconnect();
@@ -1139,6 +1193,154 @@ function createTwitch(options) {
     };
 }
 
+// Powly's sound menu for games (`powly.audio`): the player's overall volume, a mute (Powly's M
+// key), and the kinds of sound the game registers (channels: music, drawing sounds…), each with a
+// volume slider and an on/off switch, or one of them. The player sets them in Powly's options
+// bar; the game hears "change".
+//
+//   const powly = await Powly.init({
+//     audio: { channels: [{ id: "music", label: "Music" }] },
+//   });
+//   await powly.audio.register({ id: "drawing", label: "Drawing sounds", volume: false });
+//   music.volume = powly.audio.level("music");
+//   powly.audio.on("change", () => { music.volume = powly.audio.level("music"); });
+//   if (powly.audio.level("drawing") > 0) playScribble();
+//
+// The overall volume and mute apply by themselves (`auto`, on by default): the SDK puts a volume
+// control in front of the page's speakers, for Web Audio (every connection to an AudioContext's
+// destination goes through it) and for <audio>/<video> (their volume is scaled). So every game
+// on this SDK follows Powly's volume, and channels only need the channel's own value:
+// `level(channel)` is what to play at either way.
+/** Volume of the page's sound overall: 0 when muted. */
+const masterLevel = (state) => (state.muted ? 0 : state.volume);
+/** Live references to objects, for walking them later without keeping them alive. */
+function weakList() {
+    const seen = new WeakSet();
+    const refs = new Set();
+    return {
+        add(item) {
+            if (seen.has(item))
+                return false;
+            seen.add(item);
+            refs.add(new WeakRef(item));
+            return true;
+        },
+        has: (item) => seen.has(item),
+        *[Symbol.iterator]() {
+            for (const ref of refs) {
+                const item = ref.deref();
+                if (item)
+                    yield item;
+                else
+                    refs.delete(ref);
+            }
+        },
+    };
+}
+/**
+ * Puts a volume control in front of the page's speakers: Web Audio connections to a real-time
+ * AudioContext's destination go through a gain node per context, and media elements' volume is
+ * scaled (the volume the game set still reads back unchanged; elements played through Web Audio
+ * are left to the gain node). Returns how to set it.
+ */
+function installMasterGain(win = window) {
+    let level = 1;
+    // Web Audio.
+    const gainOf = new WeakMap();
+    const gains = weakList();
+    const Destination = win.AudioDestinationNode;
+    const Offline = win.OfflineAudioContext;
+    const nodeProto = win.AudioNode?.prototype;
+    const connect = nodeProto?.connect;
+    const disconnect = nodeProto?.disconnect;
+    /** The gain node standing in for `target` when it's a real-time context's destination. */
+    const standIn = (target) => {
+        if (!Destination || !(target instanceof Destination))
+            return null;
+        const context = target.context;
+        if (Offline && context instanceof Offline)
+            return null;
+        let gain = gainOf.get(context);
+        if (!gain) {
+            gain = context.createGain();
+            gain.gain.value = level;
+            gains.add(gain);
+            connect?.call(gain, target);
+            gainOf.set(context, gain);
+        }
+        return gain;
+    };
+    if (nodeProto && connect && disconnect) {
+        nodeProto.connect = function (target, ...rest) {
+            const gain = gains.has(this) ? null : standIn(target);
+            if (!gain)
+                return connect.call(this, target, ...rest);
+            connect.call(this, gain, ...rest);
+            // Chaining keeps working: connect() answers what it was given.
+            return target;
+        };
+        nodeProto.disconnect = function (...args) {
+            const gain = gains.has(this) ? null : standIn(args[0]);
+            return gain ? disconnect.call(this, gain, ...args.slice(1)) : disconnect.apply(this, args);
+        };
+    }
+    // Media elements: the volume the game set, and the one played (times `level`).
+    const media = win.HTMLMediaElement?.prototype;
+    const volume = media ? Object.getOwnPropertyDescriptor(media, "volume") : undefined;
+    const wanted = new WeakMap();
+    const elements = weakList();
+    const routed = new WeakSet();
+    const apply = (element) => {
+        const own = wanted.get(element) ?? 1;
+        volume?.set?.call(element, routed.has(element) ? own : own * level);
+    };
+    const track = (element) => {
+        if (!wanted.has(element))
+            wanted.set(element, volume?.get?.call(element) ?? 1);
+        elements.add(element);
+        apply(element);
+    };
+    if (media && volume?.get && volume.set) {
+        const { get, set } = volume;
+        Object.defineProperty(media, "volume", {
+            configurable: true,
+            enumerable: volume.enumerable,
+            get() {
+                return wanted.get(this) ?? get.call(this);
+            },
+            set(value) {
+                // Out of range throws, like the browser's own setter.
+                set.call(this, value);
+                wanted.set(this, value);
+                track(this);
+            },
+        });
+        const play = media.play;
+        media.play = function () {
+            track(this);
+            return play.call(this);
+        };
+    }
+    const createSource = win.AudioContext?.prototype.createMediaElementSource;
+    if (createSource) {
+        win.AudioContext.prototype.createMediaElementSource = function (element) {
+            routed.add(element);
+            track(element);
+            return createSource.call(this, element);
+        };
+    }
+    return {
+        set(next) {
+            level = next;
+            for (const gain of gains)
+                gain.gain.value = level;
+            for (const element of elements)
+                apply(element);
+        },
+    };
+}
+
+
 
 
 
@@ -1156,6 +1358,8 @@ function createTwitch(options) {
 //   const token = await powly.getSessionToken(); // send it to your backend, which verifies it
 //   const room = await powly.rooms.create();    // realtime parties (src/rooms.ts)
 //   await powly.twitch.connect();                // the streamer's Twitch chat (src/twitch.ts)
+//   await powly.players.open(playerId);          // Powly's profile dialog: add, block, report
+//   powly.audio.level("music");                  // Powly's sound menu (src/audio.ts)
 //
 // Nothing here is a security boundary: the game runs in the player's browser. Your backend must
 // verify session tokens (JWKS) or exchange them, and Powly checks everything server-side.
@@ -1200,6 +1404,12 @@ function init(options = {}) {
     if (origins.length === 0) {
         return Promise.reject(new PowlyError("This game only runs when launched from Powly."));
     }
+    const audioChannels = audioChannelsOf(options.audio?.channels ?? []);
+    // Before the game's engine makes a sound, so its connections go through the volume control.
+    const auto = options.audio?.auto !== false;
+    if (auto)
+        masterGain ??= installMasterGain();
+    const master = auto ? masterGain : null;
     return new Promise((resolve, reject) => {
         const channels = origins.map((origin) => {
             const channel = new MessageChannel();
@@ -1212,6 +1422,7 @@ function init(options = {}) {
                 ...(isOptionsButtonCorner(options.optionsButton) && {
                     optionsButton: options.optionsButton,
                 }),
+                audio: { channels: audioChannels },
             };
             channel.port1.onmessage = (event) => {
                 const data = event.data;
@@ -1220,7 +1431,7 @@ function init(options = {}) {
                     for (const other of channels)
                         if (other !== channel)
                             other.port1.close();
-                    resolve(createSession(channel.port1, data));
+                    resolve(createSession(channel.port1, data, { channels: audioChannels, master }));
                 }
                 else if (data?.type === "failed") {
                     clearTimeout(timer);
@@ -1238,7 +1449,22 @@ function init(options = {}) {
         }, options.timeoutMs ?? 10_000);
     });
 }
-function createSession(port, ready) {
+/** The page's volume control (src/audio.ts), put in once even if init runs again. */
+let masterGain = null;
+/** The sound settings Powly sent, with every channel (on, at full volume, when it sent none). */
+function audioStateOf(value, channels) {
+    const sent = (typeof value === "object" && value !== null ? value : {});
+    const levels = ((typeof sent.channels === "object" && sent.channels) || {});
+    return {
+        volume: volumeOf(sent.volume) ?? 1,
+        muted: sent.muted === true,
+        channels: Object.fromEntries(channels.map((channel) => {
+            const level = levels[channel.id];
+            return [channel.id, { volume: volumeOf(level?.volume) ?? 1, on: level?.on !== false }];
+        })),
+    };
+}
+function createSession(port, ready, sound) {
     let token = ready.token;
     let expiresAt = Date.now() + ready.expiresIn * 1000;
     let refreshing = null;
@@ -1247,6 +1473,23 @@ function createSession(port, ready) {
     const listeners = new Map();
     // "shown" comes once; games that listen for it later still hear it.
     let shown = false;
+    // The player's sound settings; the page's volume follows them (auto).
+    let channels = sound.channels;
+    let audio = audioStateOf(ready.audio, channels);
+    const audioListeners = new Set();
+    sound.master?.set(masterLevel(audio));
+    const setAudio = (next) => {
+        audio = next;
+        sound.master?.set(masterLevel(audio));
+        for (const listener of audioListeners) {
+            try {
+                listener(audio);
+            }
+            catch (error) {
+                console.error("[powly] an audio listener failed", error);
+            }
+        }
+    };
     port.onmessage = (event) => {
         const data = event.data;
         if (data?.type === "response") {
@@ -1260,7 +1503,13 @@ function createSession(port, ready) {
                 waiting.reject(new PowlyError(data.error));
         }
         else if (data?.type === "event") {
-            const name = data.event;
+            const message = data;
+            if (message.event === "audio") {
+                if ("audio" in message)
+                    setAudio(audioStateOf(message.audio, channels));
+                return;
+            }
+            const name = message.event;
             if (name === "shown") {
                 if (shown)
                     return;
@@ -1326,7 +1575,10 @@ function createSession(port, ready) {
         invite: sendInvite,
     });
     listeners.get("ended")?.add(() => realtime.stop());
-    const twitch = createTwitch({ getInfo: () => api("/twitch") });
+    const twitch = createTwitch({
+        getInfo: () => api("/twitch"),
+        prompt: async () => (await call("twitch.connect")).connected,
+    });
     listeners.get("ended")?.add(() => twitch.stop());
     const saves = {
         get: async (key) => {
@@ -1373,6 +1625,52 @@ function createSession(port, ready) {
                 return (await call("invites.open", { params, members }));
             },
         },
+        players: {
+            open: async (playerId, options = {}) => (await call("players.open", {
+                playerId,
+                ...(options.view && { view: options.view }),
+            })),
+        },
+        audio: {
+            get volume() {
+                return audio.volume;
+            },
+            get muted() {
+                return audio.muted;
+            },
+            get channels() {
+                return Object.fromEntries(Object.entries(audio.channels).map(([id, state]) => [id, { ...state }]));
+            },
+            level(channel) {
+                const state = channel === undefined ? undefined : audio.channels[channel];
+                const own = state ? (state.on ? state.volume : 0) : 1;
+                return sound.master ? own : own * masterLevel(audio);
+            },
+            async register(channel) {
+                const next = audioChannelsOf([
+                    ...channels.filter((existing) => existing.id !== channel?.id),
+                    channel,
+                ]);
+                if (!next.some((entry) => entry.id === channel?.id)) {
+                    throw new PowlyError(`A channel needs an id of letters, digits, _ and -, and a game has up to ${MAX_AUDIO_CHANNELS}.`);
+                }
+                // Same order as before; a changed channel keeps its place.
+                channels = [
+                    ...channels.map((existing) => next.find((entry) => entry.id === existing.id) ?? existing),
+                    ...next.filter((entry) => !channels.some((existing) => existing.id === entry.id)),
+                ];
+                const result = await call("audio.channels", { channels });
+                setAudio(audioStateOf(result, channels));
+            },
+            async set(changes) {
+                const result = await call("audio.set", { audio: changes });
+                setAudio(audioStateOf(result, channels));
+            },
+            on(_event, listener) {
+                audioListeners.add(listener);
+                return () => audioListeners.delete(listener);
+            },
+        },
         rooms: realtime.rooms,
         twitch: {
             info: twitch.info,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powly/sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Powly game SDK: launch handshake, session tokens and platform services.",
   "license": "MIT",
@@ -46,4 +46,4 @@
     "example:zip": "node scripts/example-zip.ts",
     "mirror": "node scripts/mirror.ts"
   }
-}
+}