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

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"];
+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,17 @@
+/**
+ * @memizy/protocol – Memizy Plugin Protocol v1.
+ * The normative specification is SPEC.md in this package.
+ */
+export * from './version';
+export * from './errors';
+export * from './limits';
+export * from './settingsSchema';
+export * from './settings';
+export * from './manifestSchema';
+export * from './pluginRuntime';
+export * from './types';
+export * from './schemas';
+export * from './relay';
+export * from './items';
+export * from './security';
+export * from './polyfills';

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,62 @@
+/**
+ * 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;
+    /** Max serialized size of a service request (its result may be up to `messageBytes * 4`). */
+    readonly serviceBytes: number;
+    /** Service calls per minute and instance (sustained). */
+    readonly servicesPerMinute: 30;
+};
+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';
+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';
+import { SettingDefinition } from './settingsSchema';
+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,168 @@
+/**
+ * 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`.
+ */
+export declare const RELAY_PROTOCOL = 1;
+export declare const RELAY_LIMITS: {
+    /** Max size of one WebSocket frame (UTF-8 JSON). */
+    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;
+    /** 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 RelayPlayer {
+    id: string;
+    name: string;
+    connected: boolean;
+}
+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). */
+ | {
+    t: 'join';
+    protocol: number;
+    pin: string;
+    name: string;
+    token?: 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: RelayPlayer[];
+}
+/** 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: RelayPlayer;
+    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;

package/dist/src/schemas.d.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { HostApi } from './types';
+export declare const AddressSchema: z.ZodString;
+export declare const HandshakeSchema: z.ZodObject<{
+    protocol: z.ZodString;
+    sdk: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$loose>;
+    plugin: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$loose>;
+    features: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+export declare const OutgoingMessageSchema: z.ZodObject<{
+    to: z.ZodUnion<readonly [z.ZodLiteral<"authority">, z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+    data: z.ZodUnknown;
+}, z.core.$loose>;
+export declare const AnswerRecordSchema: z.ZodObject<{
+    playerId: z.ZodOptional<z.ZodString>;
+    itemId: z.ZodString;
+    isCorrect: z.ZodBoolean;
+    confidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+    timeSpentMs: z.ZodOptional<z.ZodNumber>;
+    hintsUsed: z.ZodOptional<z.ZodNumber>;
+    isSkipped: z.ZodOptional<z.ZodBoolean>;
+    answer: z.ZodOptional<z.ZodUnknown>;
+    item: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export declare const ProgressRecordsSchema: z.ZodRecord<z.ZodString, z.ZodType<import('@memizy/oqse').ProgressRecord, unknown, z.core.$ZodTypeInternals<import('@memizy/oqse').ProgressRecord, unknown>>>;
+export declare const DataScopeSchema: z.ZodEnum<{
+    set: "set";
+    plugin: "plugin";
+}>;
+export declare const SettingsUpdateSchema: z.ZodObject<{
+    values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    valid: z.ZodBoolean;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const SessionResultSchema: z.ZodObject<{
+    scores: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const ResizeRequestSchema: z.ZodObject<{
+    height: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>;
+}, z.core.$loose>;
+export declare const ErrorReportSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+/** Argument schemas of every Host API method. */
+export declare const HOST_API_ARGS: {
+    hello: z.ZodTuple<[z.ZodObject<{
+        protocol: z.ZodString;
+        sdk: z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$loose>;
+        plugin: z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$loose>;
+        features: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>], null>;
+    ready: z.ZodTuple<[], null>;
+    send: z.ZodTuple<[z.ZodObject<{
+        to: z.ZodUnion<readonly [z.ZodLiteral<"authority">, z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+        data: z.ZodUnknown;
+    }, z.core.$loose>], null>;
+    saveSnapshot: z.ZodTuple<[z.ZodUnknown], null>;
+    recordAnswer: z.ZodTuple<[z.ZodObject<{
+        playerId: z.ZodOptional<z.ZodString>;
+        itemId: z.ZodString;
+        isCorrect: z.ZodBoolean;
+        confidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+        timeSpentMs: z.ZodOptional<z.ZodNumber>;
+        hintsUsed: z.ZodOptional<z.ZodNumber>;
+        isSkipped: z.ZodOptional<z.ZodBoolean>;
+        answer: z.ZodOptional<z.ZodUnknown>;
+        item: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>], null>;
+    saveProgress: z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodType<import('@memizy/oqse').ProgressRecord, unknown, z.core.$ZodTypeInternals<import('@memizy/oqse').ProgressRecord, unknown>>>], null>;
+    saveData: z.ZodTuple<[z.ZodEnum<{
+        set: "set";
+        plugin: "plugin";
+    }>, z.ZodUnknown], null>;
+    updateSettings: z.ZodTuple<[z.ZodObject<{
+        values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        valid: z.ZodBoolean;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], null>;
+    getAsset: z.ZodTuple<[z.ZodString, z.ZodOptional<z.ZodString>], null>;
+    end: z.ZodTuple<[z.ZodObject<{
+        scores: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], null>;
+    resize: z.ZodTuple<[z.ZodObject<{
+        height: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>;
+    }, z.core.$loose>], null>;
+    reportError: z.ZodTuple<[z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$loose>], null>;
+    exit: z.ZodTuple<[], null>;
+    service: z.ZodTuple<[z.ZodString, z.ZodUnknown], null>;
+};
+/**
+ * Validates the arguments of a Host API call.
+ * @throws {ProtocolError} `INVALID_ARGUMENT` with readable details.
+ */
+export declare function parseHostCall<M extends keyof HostApi>(method: M, args: unknown[]): Parameters<HostApi[M]>;

package/dist/src/security.d.ts

@@ -0,0 +1,21 @@
+import { PluginRuntime } from './pluginRuntime';
+/** CDNs plugins load libraries from (scripts, styles, fonts, data files). */
+export declare const LIBRARY_ORIGINS: string[];
+/** Device permissions a plugin may declare, and their iframe `allow` names. */
+export declare const PLUGIN_DEVICES: readonly ["camera", "microphone", "geolocation", "serial", "bluetooth"];
+export type PluginDevice = (typeof PLUGIN_DEVICES)[number];
+/**
+ * The Content Security Policy of a plugin iframe.
+ *
+ * - Scripts only inline (the plugin itself), from the library CDNs and from the host
+ *   (`hostOrigin`, which serves the SDK in development and in Memizy Play).
+ * - Network requests (`fetch`, WebSocket…) only to the CDNs and the declared
+ *   `permissions.network` origins.
+ * - Images and media may come from any https URL (study sets link them), so an image
+ *   URL can still carry data out: the policy blocks data channels, not every leak.
+ */
+export declare function pluginContentPolicy(runtime: Pick<PluginRuntime, 'permissions'> | null, hostOrigin: string | null): string;
+/** The iframe `allow` attribute for the declared devices (empty when none). */
+export declare function pluginAllowAttribute(runtime: Pick<PluginRuntime, 'permissions'> | null): string;
+/** Puts the policy into the plugin HTML as the first element of `<head>` (before any script). */
+export declare function injectContentPolicy(html: string, policy: string): string;

package/dist/src/settings.d.ts

@@ -0,0 +1,22 @@
+import { LocalizedText, SettingDefinition } from './settingsSchema';
+export type SettingValue = string | number | boolean;
+/** Returns an error description if `value` is not valid for `def`, otherwise `null`. */
+export declare function validateSettingValue(def: SettingDefinition, value: unknown): string | null;
+/**
+ * Builds the full settings object: every declared setting gets the valid input
+ * value or its default. Invalid values and unknown keys are reported in `errors`
+ * (and replaced by defaults / dropped).
+ */
+export declare function resolveSettings(definitions: SettingDefinition[], input?: Record<string, unknown>): {
+    values: Record<string, SettingValue>;
+    errors: string[];
+};
+/** The settings a host shows for a mode (`modes` absent = both modes). */
+export declare function settingsForMode<T extends {
+    modes?: readonly string[];
+}>(definitions: readonly T[], mode: 'solo' | 'multiplayer'): T[];
+/**
+ * Picks the best text for a locale: exact match (`cs-CZ`), language (`cs`),
+ * English, then the first available.
+ */
+export declare function localize(text: LocalizedText, locale: string): string;