@memizy/protocol 0.0.0-stage → 1.0.0-rc.6

package/dist/settingsSchema.js

@@ -0,0 +1,58 @@
+import { z as e } from "zod";
+//#region src/settingsSchema.ts
+var t = e.union([e.string().min(1, "Text must not be empty"), e.record(e.string().min(2), e.string().min(1)).refine((e) => Object.keys(e).length > 0, "Localized text needs at least one language")]), n = {
+	id: e.string().regex(/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/, "Setting id must start with a letter and contain only letters, digits, \"_\" and \"-\""),
+	label: t,
+	description: t.optional(),
+	modes: e.array(e.enum(["solo", "multiplayer"])).min(1, "modes needs at least one mode").optional()
+}, r = e.looseObject({
+	...n,
+	type: e.literal("number"),
+	default: e.number().finite(),
+	min: e.number().finite().optional(),
+	max: e.number().finite().optional(),
+	step: e.number().positive().optional()
+}).refine((e) => e.min === void 0 || e.max === void 0 || e.min <= e.max, {
+	message: "min must not be greater than max",
+	path: ["min"]
+}).refine((e) => (e.min === void 0 || e.default >= e.min) && (e.max === void 0 || e.default <= e.max), {
+	message: "default is outside min/max",
+	path: ["default"]
+}), i = e.looseObject({
+	...n,
+	type: e.literal("boolean"),
+	default: e.boolean()
+}), a = e.union([
+	e.string(),
+	e.number().finite(),
+	e.boolean()
+]), o = e.looseObject({
+	...n,
+	type: e.literal("select"),
+	options: e.array(e.looseObject({
+		value: a,
+		label: t
+	})).min(1, "A select setting needs at least one option"),
+	default: a
+}).refine((e) => new Set(e.options.map((e) => e.value)).size === e.options.length, {
+	message: "Option values must be unique",
+	path: ["options"]
+}).refine((e) => e.options.some((t) => t.value === e.default), {
+	message: "default must be one of the option values",
+	path: ["default"]
+}), s = e.looseObject({
+	...n,
+	type: e.literal("text"),
+	default: e.string(),
+	maxLength: e.number().int().positive().optional()
+}).refine((e) => e.maxLength === void 0 || e.default.length <= e.maxLength, {
+	message: "default is longer than maxLength",
+	path: ["default"]
+}), c = e.discriminatedUnion("type", [
+	r,
+	i,
+	o,
+	s
+]);
+//#endregion
+export { t as LocalizedTextSchema, c as SettingDefinitionSchema };

package/dist/src/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Protocol errors (SPEC section 8.2).
+ *
+ * Errors cross the iframe boundary through Penpal, which keeps only the
+ * error `name` and `message`. The code is therefore also encoded in the
+ * message as `[CODE] text`, and {@link toProtocolError} restores it.
+ */
+export declare const PROTOCOL_ERROR_CODES: readonly ["UNSUPPORTED_PROTOCOL", "INVALID_ARGUMENT", "NOT_AUTHORITY", "NOT_ALLOWED_IN_VIEW", "AUTHORITY_UNAVAILABLE", "MESSAGE_TOO_LARGE", "SNAPSHOT_TOO_LARGE", "DATA_TOO_LARGE", "RATE_LIMITED", "ASSET_NOT_FOUND", "SESSION_ENDED", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "UNKNOWN_METHOD"];
+export type ProtocolErrorCode = (typeof PROTOCOL_ERROR_CODES)[number];
+export declare class ProtocolError extends Error {
+    readonly code: ProtocolErrorCode;
+    constructor(code: ProtocolErrorCode, message: string);
+    /** The message without the `[CODE]` prefix. */
+    get detail(): string;
+}
+export declare function isProtocolErrorCode(value: unknown): value is ProtocolErrorCode;
+/**
+ * Converts anything thrown by a remote call into a {@link ProtocolError}.
+ * Unknown codes and foreign errors become `INTERNAL_ERROR` (SPEC 8.2).
+ */
+export declare function toProtocolError(error: unknown): ProtocolError;

package/dist/src/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @memizy/protocol – Memizy Plugin Protocol v1.
+ * The normative specification is SPEC.md in this package.
+ *
+ * The public API is listed explicitly: it follows semver within 1.x. Helpers shared by the
+ * Memizy packages (rate limiting, call parsing, content policies…) are in
+ * `@memizy/protocol/internal` and may change in any release.
+ */
+export { PROTOCOL_VERSION, parseProtocolVersion, compareProtocolVersions, negotiateProtocolVersion, isProtocolSupported, type ProtocolVersion, type HostProtocolVersions, } from './version.js';
+export { PROTOCOL_ERROR_CODES, ProtocolError, isProtocolErrorCode, toProtocolError, type ProtocolErrorCode } from './errors.js';
+export { LIMITS, type Limits } from './limits.js';
+export { LocalizedTextSchema, SettingDefinitionSchema, type LocalizedText, type SettingDefinition } from './settingsSchema.js';
+export { validateSettingValue, resolveSettings, settingsForMode, localize, type SettingValue } from './settings.js';
+export { HostAsSchema, MultiplayerModeSchema, ServiceNameSchema, PluginPermissionsSchema, MemizyRuntimeSchema, PluginManifestError, safeParsePluginManifest, parsePluginManifest, readPluginManifestFromHtml, type MemizyRuntimeManifest, type PluginManifest, type PluginManifestResult, } from './manifestSchema.js';
+export { extractManifestFromHtml, type HostAs, type PluginView, type PluginRuntime } from './pluginRuntime.js';
+export * from './types.js';
+export { AddressSchema, HandshakeSchema, OutgoingMessageSchema, AnswerRecordSchema, DataScopeSchema, SettingsUpdateSchema, SessionResultSchema, ErrorReportSchema, } from './schemas.js';
+export { RELAY_PROTOCOL, type RelayBundle, type CreateRoomResponse, type RoomInfo, type RoomPlayer, type RelayClientMessage, type RelayErrorCode, type RelayServerMessage, } from './relay.js';
+export { prepareDisplaySet, type DisplaySet, type PublicItemMark } from './items.js';
+export { PLUGIN_DEVICES, type PluginDevice } from './security.js';

package/dist/src/internal.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @memizy/protocol/internal – helpers shared by the Memizy packages (host-sdk, plugin-sdk,
+ * the relay server, Memizy Play). Not part of the public API: they may change in any
+ * release. Use `@memizy/protocol` instead.
+ */
+export { findNonJson, jsonByteSize, assertJsonWithin, RateLimiter } from './limits.js';
+export { toRuntime } from './pluginRuntime.js';
+export { HOST_API_ARGS, parseHostCall } from './schemas.js';
+export { RELAY_LIMITS, normalizePlayerName, isPin } from './relay.js';
+export { seededRandom, displayItem, publicItem } from './items.js';
+export { LIBRARY_ORIGINS, pluginContentPolicy, pluginAllowAttribute, injectContentPolicy } from './security.js';
+export { ensureConnectionPolyfills } from './polyfills.js';

package/dist/src/items.d.ts

@@ -0,0 +1,27 @@
+import { OQSEAnyItem, OQSEMeta } from '@memizy/oqse';
+/** Marks an item whose answer was removed (multiplayer, not the authority). */
+export interface PublicItemMark {
+    answerHidden?: true;
+}
+export interface DisplaySet {
+    meta: OQSEMeta;
+    items: OQSEAnyItem[];
+}
+export declare function seededRandom(seed: string): () => number;
+/** The item in display order. Answers refer to IDs, so only the lists move. */
+export declare function displayItem(item: OQSEAnyItem, random: () => number): OQSEAnyItem;
+/**
+ * The item without its answer. Custom (`x-`) types lose only `solution` (where OQSE
+ * puts everything that gives their answer away) and the common fields. `hints` stay:
+ * a game may show them on any device while the player answers.
+ */
+export declare function publicItem(item: OQSEAnyItem): OQSEAnyItem;
+/**
+ * The set of a session: `set` in display order with answers (the authority,
+ * solo), `publicSet` without answers (the other instances in multiplayer).
+ * Without a seed nothing is shuffled.
+ */
+export declare function prepareDisplaySet(set: DisplaySet, seed?: string): {
+    set: DisplaySet;
+    publicSet: DisplaySet;
+};

package/dist/src/limits.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Limits (SPEC section 8.1) and JSON value checks.
+ *
+ * The values are guaranteed minimums: a host MUST accept at least this much
+ * and MAY allow more. Plugins (and the SDK) MUST stay within them.
+ */
+export declare const LIMITS: {
+    /** Max serialized size of one `send` message (bytes of UTF-8 JSON). */
+    readonly messageBytes: number;
+    /** Sustained `send` rate per instance (messages per second). */
+    readonly messagesPerSecond: 30;
+    /** Burst size of the `send` rate limiter. */
+    readonly messageBurst: 60;
+    /** Max serialized size of a snapshot. */
+    readonly snapshotBytes: number;
+    /** Snapshots per second the host stores (more are coalesced). */
+    readonly snapshotsPerSecond: 2;
+    /** Max serialized size of plugin data per scope. */
+    readonly dataBytes: number;
+    /** Plugin data writes per second and scope the host stores (more are coalesced). */
+    readonly dataWritesPerSecond: 1;
+    /** Max time between the iframe load and `hello`. */
+    readonly helloTimeoutMs: 10000;
+    /** Max serialized size of the player's answer in `recordAnswer`. */
+    readonly answerBytes: number;
+    /** Max serialized size of a generated item attached to `recordAnswer`. */
+    readonly generatedItemBytes: number;
+    /** `recordAnswer` calls per second and instance (sustained); the authority: per player. */
+    readonly answersPerSecond: 10;
+    /** Burst size of the `recordAnswer` rate limiter. */
+    readonly answerBurst: 20;
+    /** Max serialized size of a service request. */
+    readonly serviceBytes: number;
+    /** Max serialized size of a service result. */
+    readonly serviceResultBytes: number;
+    /** Service calls per minute and instance (sustained). */
+    readonly servicesPerMinute: 30;
+    /** `getAsset` calls per second and instance (sustained). */
+    readonly assetsPerSecond: 10;
+    /** Burst size of the `getAsset` rate limiter. */
+    readonly assetBurst: 20;
+    /** Size of one asset every host can deliver through `getAsset`. */
+    readonly assetBytes: number;
+    /** `reportError` calls per second and instance the host keeps (more are dropped). */
+    readonly errorReportsPerSecond: 5;
+    /** Burst size of the `reportError` limiter. */
+    readonly errorReportBurst: 10;
+};
+export type Limits = {
+    [K in keyof typeof LIMITS]: number;
+};
+/**
+ * Checks that `value` is plain JSON (null, booleans, finite numbers, strings,
+ * arrays and plain objects; no cycles, no `undefined`, functions, Dates, Maps…).
+ * Returns an error description, or `null` when the value is valid.
+ */
+export declare function findNonJson(value: unknown, path?: string, depth?: number, seen?: Set<object>): string | null;
+/** UTF-8 byte size of the JSON serialization of a (valid JSON) value. */
+export declare function jsonByteSize(value: unknown): number;
+/**
+ * Throws `INVALID_ARGUMENT` if `value` is not plain JSON, or `tooLargeCode`
+ * if its serialized size exceeds `maxBytes`. Returns the size in bytes.
+ */
+export declare function assertJsonWithin(value: unknown, maxBytes: number, tooLargeCode: 'MESSAGE_TOO_LARGE' | 'SNAPSHOT_TOO_LARGE' | 'DATA_TOO_LARGE', what: string): number;
+/**
+ * Token bucket rate limiter (`rate` tokens per second, up to `burst` stored).
+ * Used by the host for `send`; also usable by the SDK to stay within limits.
+ */
+export declare class RateLimiter {
+    private readonly rate;
+    private readonly burst;
+    private readonly now;
+    private tokens;
+    private last;
+    constructor(rate: number, burst: number, now?: () => number);
+    /** Takes `cost` tokens (default one). Returns `false` when the limit is exceeded. */
+    tryTake(cost?: number): boolean;
+}

package/dist/src/manifestSchema.d.ts

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+import { OQSEManifest } from '@memizy/oqse';
+import { PluginRuntime } from './pluginRuntime.js';
+export declare const HostAsSchema: z.ZodEnum<{
+    presenter: "presenter";
+    player: "player";
+}>;
+export declare const MultiplayerModeSchema: z.ZodObject<{
+    players: z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+        recommended: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    hostAs: z.ZodArray<z.ZodEnum<{
+        presenter: "presenter";
+        player: "player";
+    }>>;
+    lateJoin: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+/** Service names are dot-separated lowercase segments, e.g. "ai.chat" or "chess.puzzles". */
+export declare const ServiceNameSchema: z.ZodString;
+export declare const PluginPermissionsSchema: z.ZodObject<{
+    network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    devices: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        camera: "camera";
+        microphone: "microphone";
+        geolocation: "geolocation";
+        serial: "serial";
+        bluetooth: "bluetooth";
+    }>>>;
+}, z.core.$loose>;
+export declare const MemizyRuntimeSchema: z.ZodObject<{
+    protocol: z.ZodString;
+    set: z.ZodOptional<z.ZodEnum<{
+        optional: "optional";
+        required: "required";
+        none: "none";
+    }>>;
+    modes: z.ZodObject<{
+        solo: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+        multiplayer: z.ZodOptional<z.ZodObject<{
+            players: z.ZodObject<{
+                min: z.ZodNumber;
+                max: z.ZodNumber;
+                recommended: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>;
+            hostAs: z.ZodArray<z.ZodEnum<{
+                presenter: "presenter";
+                player: "player";
+            }>>;
+            lateJoin: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    settings: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"number">;
+        default: z.ZodNumber;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        step: z.ZodOptional<z.ZodNumber>;
+        id: z.ZodString;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            solo: "solo";
+            multiplayer: "multiplayer";
+        }>>>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"boolean">;
+        default: z.ZodBoolean;
+        id: z.ZodString;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            solo: "solo";
+            multiplayer: "multiplayer";
+        }>>>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"select">;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+            label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        }, z.core.$loose>>;
+        default: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+        id: z.ZodString;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            solo: "solo";
+            multiplayer: "multiplayer";
+        }>>>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        default: z.ZodString;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        id: z.ZodString;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            solo: "solo";
+            multiplayer: "multiplayer";
+        }>>>;
+    }, z.core.$loose>], "type">>>;
+    settingsScreen: z.ZodOptional<z.ZodObject<{
+        size: z.ZodEnum<{
+            compact: "compact";
+            large: "large";
+        }>;
+    }, z.core.$loose>>;
+    display: z.ZodOptional<z.ZodObject<{
+        orientation: z.ZodOptional<z.ZodEnum<{
+            any: "any";
+            portrait: "portrait";
+            landscape: "landscape";
+        }>>;
+    }, z.core.$loose>>;
+    permissions: z.ZodOptional<z.ZodObject<{
+        network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        devices: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            camera: "camera";
+            microphone: "microphone";
+            geolocation: "geolocation";
+            serial: "serial";
+            bluetooth: "bluetooth";
+        }>>>;
+    }, z.core.$loose>>;
+    services: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type MemizyRuntimeManifest = z.infer<typeof MemizyRuntimeSchema>;
+/** A plugin manifest: OQSEM plus the required `appSpecific.memizy` block. */
+export type PluginManifest = OQSEManifest & {
+    appSpecific: Record<string, unknown> & {
+        memizy: MemizyRuntimeManifest;
+    };
+};
+export type PluginManifestResult = {
+    success: true;
+    manifest: PluginManifest;
+    runtime: PluginRuntime;
+} | {
+    success: false;
+    errors: string[];
+};
+/**
+ * Validates a plugin manifest (OQSEM part and Memizy runtime part).
+ * The returned `manifest` is the original object (unknown keys preserved).
+ */
+export declare function safeParsePluginManifest(data: unknown): PluginManifestResult;
+/** Error thrown by {@link parsePluginManifest}. */
+export declare class PluginManifestError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/** Like {@link safeParsePluginManifest}, but throws {@link PluginManifestError}. */
+export declare function parsePluginManifest(data: unknown): {
+    manifest: PluginManifest;
+    runtime: PluginRuntime;
+};
+/** Extracts and validates the manifest of a plugin HTML file. */
+export declare function readPluginManifestFromHtml(html: string): PluginManifestResult;

package/dist/src/pluginRuntime.d.ts

@@ -0,0 +1,47 @@
+import { MemizyRuntimeManifest } from './manifestSchema.js';
+import { SettingDefinition } from './settingsSchema.js';
+export type HostAs = 'presenter' | 'player';
+export type PluginView = 'solo' | 'board' | 'controller' | 'settings';
+/** The runtime part with all defaults applied – what hosts work with. */
+export interface PluginRuntime {
+    protocol: string;
+    /** Whether the plugin uses a study set: `none` = a game without questions. */
+    set: 'required' | 'optional' | 'none';
+    solo: boolean;
+    multiplayer: null | {
+        players: {
+            min: number;
+            max: number;
+            recommended?: number;
+        };
+        hostAs: HostAs[];
+        lateJoin: boolean;
+    };
+    settings: SettingDefinition[];
+    settingsScreen: null | {
+        size: 'compact' | 'large';
+    };
+    orientation: 'any' | 'portrait' | 'landscape';
+    /** Views the plugin must render (SPEC 3.2). */
+    views: PluginView[];
+    /** Declared network origins and devices (SPEC 8.4). */
+    permissions: {
+        network: string[];
+        devices: ('camera' | 'microphone' | 'geolocation' | 'serial' | 'bluetooth')[];
+    };
+    /** Memizy services the plugin uses (SPEC 5.3). */
+    services: string[];
+}
+/**
+ * Reads the manifest data island from plugin HTML **without executing it**
+ * (works in browsers and in Node). Returns the parsed JSON, or an error.
+ */
+export declare function extractManifestFromHtml(html: string): {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    error: string;
+};
+/** Applies defaults and derives the views (SPEC 3.2). */
+export declare function toRuntime(memizy: MemizyRuntimeManifest): PluginRuntime;

package/dist/src/polyfills.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Small polyfills for what the connection library (Penpal 8) needs from the browser, so
+ * older school devices (Safari before 17.4) still run games. Called right before
+ * connecting; it only adds what is missing.
+ */
+export declare function ensureConnectionPolyfills(): void;

package/dist/src/relay.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Relay wire protocol: the host app and player apps ↔ the Memizy multiplayer
+ * server (WebSocket, JSON text frames). Plugins never see it (SPEC D2).
+ *
+ * The server is a room relay: PINs, player identity (reconnect tokens),
+ * presence and forwarding between the host and the players. The game session
+ * itself (validation, limits, authority, state) runs in the host's browser.
+ * The plugin and the study set are uploaded once over HTTP and downloaded by
+ * the players over HTTP (`RelayBundle`), not sent through the WebSocket.
+ *
+ * HTTP API (JSON):
+ * - `POST /api/rooms` → `CreateRoomResponse`
+ * - `GET  /api/rooms/:pin` → `RoomInfo` (404 if unknown)
+ * - `PUT  /api/rooms/:pin/bundle` (header `Authorization: Bearer <hostToken>`, body `RelayBundle`) → `{ version }`
+ * - `GET  /api/rooms/:pin/bundle` → `RelayBundle` (header `X-Bundle-Version`)
+ * - `GET  /api/health`
+ * WebSocket: `/ws`.
+ */
+/**
+ * Version of the relay wire protocol (client <-> server). Within version 1 messages only
+ * change additively: receivers ignore unknown fields; the server answers an unknown `t`
+ * with a non-fatal `NOT_ALLOWED` error. The messages between the host app and the player
+ * apps (inside `data`) have their own version (`RELAY_APP_VERSION` in @memizy/host-sdk).
+ */
+export declare const RELAY_PROTOCOL = 1;
+export declare const RELAY_LIMITS: {
+    /** Max size of one WebSocket frame (UTF-8 JSON); fits an asset of `LIMITS.assetBytes` as base64. */
+    readonly frameBytes: number;
+    /** Max size of an uploaded bundle (plugin + set). */
+    readonly bundleBytes: number;
+    /** Max players in a room (the plugin may allow fewer). */
+    readonly playersPerRoom: 100;
+    /** Player frames per second (sustained / burst). */
+    readonly playerFramesPerSecond: 60;
+    readonly playerFrameBurst: 120;
+    /** Host frames per second (it talks to every player). */
+    readonly hostFramesPerSecond: 3000;
+    readonly hostFrameBurst: 6000;
+    /** Max player name length. */
+    readonly nameLength: 32;
+    /** Max length of the `auth` a player sends when joining. */
+    readonly authLength: 4096;
+    /** A room is closed when its host has been away this long. */
+    readonly hostAwayMs: number;
+    /** A room is closed after this time in any case. */
+    readonly roomTtlMs: number;
+};
+/** What the players download: the plugin HTML and the set prepared for it. */
+export interface RelayBundle {
+    pluginHtml: string;
+    /** The set as delivered to plugins (`InitPayload.set`). */
+    set: unknown;
+}
+export interface CreateRoomResponse {
+    pin: string;
+    hostToken: string;
+}
+export interface RoomInfo {
+    pin: string;
+    /** Whether new players can join right now. */
+    open: boolean;
+    /** Name of the game (once the host uploaded a bundle). */
+    appName: string | null;
+    players: number;
+}
+export interface RoomPlayer {
+    id: string;
+    name: string;
+    connected: boolean;
+    /**
+     * What the player's app sent as `auth` when joining (e.g. a signed token of a signed-in
+     * student). Only the host gets it; the server does not check it – the host app does.
+     */
+    auth?: string;
+}
+export type RelayClientMessage = 
+/** The host attaches to its room (also after a reconnect). */
+{
+    t: 'host';
+    protocol: number;
+    pin: string;
+    hostToken: string;
+}
+/**
+ * A player joins (with `token`: rejoins as the same player). `auth` (optional, at most
+ * `RELAY_LIMITS.authLength` characters) is passed to the host only, for apps with
+ * signed-in players; a rejoin with `auth` replaces the earlier one.
+ */
+ | {
+    t: 'join';
+    protocol: number;
+    pin: string;
+    name: string;
+    token?: string;
+    auth?: string;
+}
+/** Host → one player. */
+ | {
+    t: 'to';
+    to: string;
+    data: unknown;
+}
+/** Host: allow or stop new players joining. */
+ | {
+    t: 'open';
+    open: boolean;
+}
+/** Host: remove a player (they cannot rejoin with their token). */
+ | {
+    t: 'kick';
+    playerId: string;
+}
+/** Host: close the room for everyone. */
+ | {
+    t: 'close';
+}
+/** Player → host. */
+ | {
+    t: 'up';
+    data: unknown;
+}
+/** Player: change the name. */
+ | {
+    t: 'rename';
+    name: string;
+} | {
+    t: 'ping';
+};
+export type RelayErrorCode = 'BAD_MESSAGE' | 'UNSUPPORTED_PROTOCOL' | 'ROOM_NOT_FOUND' | 'ROOM_CLOSED' | 'ROOM_FULL' | 'NOT_ALLOWED' | 'KICKED' | 'RATE_LIMITED' | 'TOO_LARGE';
+export type RelayServerMessage = 
+/** To the host after `host`: the current roster. */
+{
+    t: 'hosting';
+    pin: string;
+    players: RoomPlayer[];
+}
+/** To a player after `join`. Keep `token` to rejoin as the same player. */
+ | {
+    t: 'joined';
+    pin: string;
+    playerId: string;
+    token: string;
+    name: string;
+    hostConnected: boolean;
+}
+/** To the host: a player joined, reconnected, disconnected or was renamed. */
+ | {
+    t: 'presence';
+    player: RoomPlayer;
+    event: 'join' | 'connect' | 'disconnect' | 'rename' | 'leave';
+}
+/** To players: the host connection state. */
+ | {
+    t: 'host-presence';
+    connected: boolean;
+}
+/** Player → host. */
+ | {
+    t: 'from';
+    from: string;
+    data: unknown;
+}
+/** Host → player. */
+ | {
+    t: 'data';
+    data: unknown;
+}
+/** A request failed; fatal errors are followed by closing the socket. */
+ | {
+    t: 'error';
+    code: RelayErrorCode;
+    message: string;
+    fatal: boolean;
+}
+/** The room was closed by the host or expired. */
+ | {
+    t: 'closed';
+    reason: 'host' | 'expired' | 'kicked';
+} | {
+    t: 'pong';
+    time: number;
+};
+/** Normalizes a player name (trimmed, collapsed spaces, max length). */
+export declare function normalizePlayerName(name: unknown): string;
+/** A 6-digit PIN. */
+export declare function isPin(value: unknown): value is string;