@memizy/protocol 1.0.0-rc.5 → 1.0.0-rc.7

package/dist/settingsSchema.js

@@ -1,58 +1,74 @@
-import { z as e } from "zod";
+import { SETTING_TYPES as e } from "./settings.js";
+import { z as t } 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()
+var n = t.union([t.string().min(1, "Text must not be empty"), t.record(t.string().min(2), t.string().min(1)).refine((e) => Object.keys(e).length > 0, "Localized text needs at least one language")]), r = {
+	id: t.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: n,
+	description: n.optional(),
+	modes: t.array(t.enum(["solo", "multiplayer"])).min(1, "modes needs at least one mode").optional()
+}, i = t.looseObject({
+	...r,
+	type: t.literal("number"),
+	default: t.number().finite(),
+	min: t.number().finite().optional(),
+	max: t.number().finite().optional(),
+	step: t.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
+}), a = t.looseObject({
+	...r,
+	type: t.literal("boolean"),
+	default: t.boolean()
+}), o = t.union([
+	t.string(),
+	t.number().finite(),
+	t.boolean()
+]), s = t.looseObject({
+	...r,
+	type: t.literal("select"),
+	options: t.array(t.looseObject({
+		value: o,
+		label: n
 	})).min(1, "A select setting needs at least one option"),
-	default: a
+	default: o
 }).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()
+}), c = t.looseObject({
+	...r,
+	type: t.literal("text"),
+	default: t.string(),
+	maxLength: t.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,
+}), l = t.discriminatedUnion("type", [
 	i,
-	o,
-	s
-]);
+	a,
+	s,
+	c
+]), u = t.looseObject({
+	...r,
+	type: t.string().regex(/^[a-z][a-z0-9-]*$/, "A setting type is a lowercase name").refine((t) => !e.includes(t), "A known setting type"),
+	default: t.unknown().refine((e) => e !== void 0, "A setting needs a default")
+}), d = t.unknown().transform((n, r) => {
+	let i = typeof n == "object" && n ? n.type : void 0, a = (typeof i == "string" && e.includes(i) ? l : u).safeParse(n);
+	if (!a.success) {
+		for (let e of a.error.issues) r.addIssue({
+			code: "custom",
+			message: e.message,
+			path: e.path
+		});
+		return t.NEVER;
+	}
+	return a.data;
+});
 //#endregion
-export { t as LocalizedTextSchema, c as SettingDefinitionSchema };
+export { n as LocalizedTextSchema, l as SettingDefinitionSchema, d as SettingEntrySchema, u as UnknownSettingSchema };

package/dist/src/errors.d.ts

@@ -5,7 +5,7 @@
  * 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 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;

package/dist/src/index.d.ts

@@ -1,17 +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 * 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';
+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, UnknownSettingSchema, type LocalizedText, type SettingDefinition } from './settingsSchema.js';
+export { validateSettingValue, resolveSettings, settingsForMode, localize, isKnownSetting, SETTING_TYPES, type SettingValue, type UnknownSettingDefinition } 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

@@ -11,9 +11,12 @@ 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.
+ * The item without its answer. An official type keeps only the fields its OQSE schema lists
+ * (fail closed: unknown fields, also nested, are removed, as are free-form `appSpecific` and
+ * `customData`), then loses the fields that give the answer away. Custom (`x-`) types keep
+ * their own fields and 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;
 /**

package/dist/src/limits.d.ts

@@ -25,10 +25,26 @@ export declare const LIMITS: {
     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`). */
+    /** `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;

package/dist/src/manifestSchema.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { OQSEManifest } from '@memizy/oqse';
-import { PluginRuntime } from './pluginRuntime';
+import { PluginRuntime } from './pluginRuntime.js';
 export declare const HostAsSchema: z.ZodEnum<{
     presenter: "presenter";
     player: "player";
@@ -51,55 +51,48 @@ export declare const MemizyRuntimeSchema: z.ZodObject<{
             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">>>;
+    settings: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodUnknown, z.ZodTransform<import('./settings.js').UnknownSettingDefinition | {
+        [x: string]: unknown;
+        type: "number";
+        default: number;
+        id: string;
+        label: string | Record<string, string>;
+        min?: number | undefined;
+        max?: number | undefined;
+        step?: number | undefined;
+        description?: string | Record<string, string> | undefined;
+        modes?: ("solo" | "multiplayer")[] | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "select";
+        options: {
+            [x: string]: unknown;
+            value: string | number | boolean;
+            label: string | Record<string, string>;
+        }[];
+        default: string | number | boolean;
+        id: string;
+        label: string | Record<string, string>;
+        description?: string | Record<string, string> | undefined;
+        modes?: ("solo" | "multiplayer")[] | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "text";
+        default: string;
+        id: string;
+        label: string | Record<string, string>;
+        maxLength?: number | undefined;
+        description?: string | Record<string, string> | undefined;
+        modes?: ("solo" | "multiplayer")[] | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "boolean";
+        default: boolean;
+        id: string;
+        label: string | Record<string, string>;
+        description?: string | Record<string, string> | undefined;
+        modes?: ("solo" | "multiplayer")[] | undefined;
+    }, unknown>>>>;
     settingsScreen: z.ZodOptional<z.ZodObject<{
         size: z.ZodEnum<{
             compact: "compact";

package/dist/src/pluginRuntime.d.ts

@@ -1,5 +1,6 @@
-import { MemizyRuntimeManifest } from './manifestSchema';
-import { SettingDefinition } from './settingsSchema';
+import { MemizyRuntimeManifest } from './manifestSchema.js';
+import { SettingDefinition } from './settingsSchema.js';
+import { UnknownSettingDefinition } from './settings.js';
 export type HostAs = 'presenter' | 'player';
 export type PluginView = 'solo' | 'board' | 'controller' | 'settings';
 /** The runtime part with all defaults applied – what hosts work with. */
@@ -18,6 +19,11 @@ export interface PluginRuntime {
         lateJoin: boolean;
     };
     settings: SettingDefinition[];
+    /**
+     * Settings of types from a later protocol version (SPEC 2): not shown; the plugin gets
+     * their `default` (pass them to `resolveSettings`).
+     */
+    unknownSettings: UnknownSettingDefinition[];
     settingsScreen: null | {
         size: 'compact' | 'large';
     };

package/dist/src/relay.d.ts

@@ -16,9 +16,15 @@
  * - `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). */
+    /** 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;
@@ -32,6 +38,8 @@ export declare const RELAY_LIMITS: {
     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. */
@@ -55,10 +63,15 @@ export interface RoomInfo {
     appName: string | null;
     players: number;
 }
-export interface RelayPlayer {
+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). */
@@ -68,13 +81,18 @@ export type RelayClientMessage =
     pin: string;
     hostToken: string;
 }
-/** A player joins (with `token`: rejoins as the same player). */
+/**
+ * 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. */
  | {
@@ -114,7 +132,7 @@ export type RelayServerMessage =
 {
     t: 'hosting';
     pin: string;
-    players: RelayPlayer[];
+    players: RoomPlayer[];
 }
 /** To a player after `join`. Keep `token` to rejoin as the same player. */
  | {
@@ -128,7 +146,7 @@ export type RelayServerMessage =
 /** To the host: a player joined, reconnected, disconnected or was renamed. */
  | {
     t: 'presence';
-    player: RelayPlayer;
+    player: RoomPlayer;
     event: 'join' | 'connect' | 'disconnect' | 'rename' | 'leave';
 }
 /** To players: the host connection state. */

package/dist/src/schemas.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { HostApi } from './types';
+import { HostApi } from './types.js';
 export declare const AddressSchema: z.ZodString;
 export declare const HandshakeSchema: z.ZodObject<{
     protocol: z.ZodString;
@@ -25,13 +25,13 @@ export declare const AnswerRecordSchema: z.ZodObject<{
     timeSpentMs: z.ZodOptional<z.ZodNumber>;
     hintsUsed: z.ZodOptional<z.ZodNumber>;
     isSkipped: z.ZodOptional<z.ZodBoolean>;
+    score: z.ZodOptional<z.ZodNumber>;
     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";
@@ -45,9 +45,6 @@ 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;
@@ -81,13 +78,13 @@ export declare const HOST_API_ARGS: {
         timeSpentMs: z.ZodOptional<z.ZodNumber>;
         hintsUsed: z.ZodOptional<z.ZodNumber>;
         isSkipped: z.ZodOptional<z.ZodBoolean>;
+        score: z.ZodOptional<z.ZodNumber>;
         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";
@@ -102,15 +99,11 @@ export declare const HOST_API_ARGS: {
         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>;
 };
 /**

package/dist/src/security.d.ts

@@ -1,4 +1,4 @@
-import { PluginRuntime } from './pluginRuntime';
+import { PluginRuntime } from './pluginRuntime.js';
 /** 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. */

package/dist/src/settings.d.ts

@@ -1,5 +1,24 @@
-import { LocalizedText, SettingDefinition } from './settingsSchema';
-export type SettingValue = string | number | boolean;
+import { LocalizedText, SettingDefinition } from './settingsSchema.js';
+/** Setting types of this protocol version. */
+export declare const SETTING_TYPES: readonly ["number", "boolean", "select", "text"];
+/**
+ * A setting of a type from a later protocol version (SPEC 2): hosts do not show it and pass
+ * its `default` to the plugin.
+ */
+export interface UnknownSettingDefinition {
+    id: string;
+    type: string;
+    default: unknown;
+    label: LocalizedText;
+    description?: LocalizedText;
+    modes?: ('solo' | 'multiplayer')[];
+}
+/** Whether a manifest setting is of a type this protocol version defines. */
+export declare function isKnownSetting(def: SettingDefinition | UnknownSettingDefinition): def is SettingDefinition;
+/** A setting value: a number, boolean or text, or any JSON (a setting type of a later version). */
+export type SettingValue = string | number | boolean | null | SettingValue[] | {
+    [key: string]: SettingValue;
+};
 /** Returns an error description if `value` is not valid for `def`, otherwise `null`. */
 export declare function validateSettingValue(def: SettingDefinition, value: unknown): string | null;
 /**
@@ -7,7 +26,9 @@ export declare function validateSettingValue(def: SettingDefinition, value: unkn
  * 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>): {
+export declare function resolveSettings(definitions: SettingDefinition[], input?: Record<string, unknown>, 
+/** Settings of types from a later version: always their default; input values are ignored. */
+unknownSettings?: UnknownSettingDefinition[]): {
     values: Record<string, SettingValue>;
     errors: string[];
 };

package/dist/src/settingsSchema.d.ts

@@ -1,7 +1,9 @@
 import { z } from 'zod';
+import { UnknownSettingDefinition } from './settings.js';
 /** A string, or a map of BCP 47 language → string (e.g. `{ "cs": "Čas", "en": "Time" }`). */
 export declare const LocalizedTextSchema: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
 export type LocalizedText = z.infer<typeof LocalizedTextSchema>;
+/** A setting of a type this protocol version defines (SPEC 2). */
 export declare const SettingDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"number">;
     default: z.ZodNumber;
@@ -52,3 +54,64 @@ export declare const SettingDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     }>>>;
 }, z.core.$loose>], "type">;
 export type SettingDefinition = z.infer<typeof SettingDefinitionSchema>;
+/**
+ * A setting of a type from a later protocol version (SPEC 2): hosts do not show it and
+ * pass its `default` (any JSON value) to the plugin.
+ */
+export declare const UnknownSettingSchema: z.ZodObject<{
+    type: z.ZodString;
+    default: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+    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>;
+/**
+ * One entry of `settings` in a manifest: a known setting (validated by its type, with clear
+ * messages) or a setting of a later version (only `id`, `label`, `default`).
+ */
+export declare const SettingEntrySchema: z.ZodPipe<z.ZodUnknown, z.ZodTransform<UnknownSettingDefinition | {
+    [x: string]: unknown;
+    type: "number";
+    default: number;
+    id: string;
+    label: string | Record<string, string>;
+    min?: number | undefined;
+    max?: number | undefined;
+    step?: number | undefined;
+    description?: string | Record<string, string> | undefined;
+    modes?: ("solo" | "multiplayer")[] | undefined;
+} | {
+    [x: string]: unknown;
+    type: "select";
+    options: {
+        [x: string]: unknown;
+        value: string | number | boolean;
+        label: string | Record<string, string>;
+    }[];
+    default: string | number | boolean;
+    id: string;
+    label: string | Record<string, string>;
+    description?: string | Record<string, string> | undefined;
+    modes?: ("solo" | "multiplayer")[] | undefined;
+} | {
+    [x: string]: unknown;
+    type: "text";
+    default: string;
+    id: string;
+    label: string | Record<string, string>;
+    maxLength?: number | undefined;
+    description?: string | Record<string, string> | undefined;
+    modes?: ("solo" | "multiplayer")[] | undefined;
+} | {
+    [x: string]: unknown;
+    type: "boolean";
+    default: boolean;
+    id: string;
+    label: string | Record<string, string>;
+    description?: string | Record<string, string> | undefined;
+    modes?: ("solo" | "multiplayer")[] | undefined;
+}, unknown>>;