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

package/dist/src/settingsSchema.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+/** 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>;
+export declare const SettingDefinitionSchema: 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">;
+export type SettingDefinition = z.infer<typeof SettingDefinitionSchema>;

package/dist/src/types.d.ts

@@ -0,0 +1,190 @@
+import { OQSEAnyItem, OQSEMeta, ProgressRecord } from '@memizy/oqse';
+import { HostAs, PluginView } from './pluginRuntime';
+/** Address of an instance: a player ID, `"board"`; `"server"` is reserved. */
+export type Address = string;
+/** Address of the presenter's board. */
+export declare const BOARD_ADDRESS = "board";
+/** Reserved for a future server-side authority (SPEC 3.1). */
+export declare const SERVER_ADDRESS = "server";
+export type SessionMode = 'solo' | 'multiplayer';
+export interface Player {
+    id: string;
+    name: string;
+    isHost: boolean;
+    connected: boolean;
+}
+export interface SessionInfo {
+    id: string;
+    mode: SessionMode;
+    /** `null` in solo. */
+    hostAs: HostAs | null;
+    view: PluginView;
+    /** This instance. */
+    self: Address;
+    /** Who owns the game state. */
+    authority: Address;
+    /** This instance joined a running game. */
+    lateJoin: boolean;
+}
+export interface Handshake {
+    /** Protocol version the SDK speaks, e.g. `"1.0"`. */
+    protocol: string;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    plugin: {
+        id: string;
+        version: string;
+    };
+    features: string[];
+}
+export interface Theme {
+    locale: string;
+    theme: 'light' | 'dark';
+}
+export type DataScope = 'plugin' | 'set';
+export interface PluginData {
+    /** Data across all sets (`null` = nothing saved yet). */
+    plugin: unknown;
+    /** Data for this plugin and the current set (`null` = nothing saved yet). */
+    set: unknown;
+}
+export interface InitPayload {
+    /** Negotiated version: same MAJOR, the lower MINOR. */
+    protocol: string;
+    host: {
+        name: string;
+        version: string;
+    };
+    oqseVersion: string;
+    features: string[];
+    session: SessionInfo;
+    /** Current roster (the presenter is not a player). */
+    players: Player[];
+    set: {
+        meta: OQSEMeta;
+        items: OQSEAnyItem[];
+    };
+    /** Values for every declared setting (defaults applied). */
+    settings: Record<string, unknown>;
+    config: Theme;
+    /** The session clock and its pauses (see {@link SessionClock}). */
+    clock: SessionClock;
+    /**
+     * RC4: Memizy services this host offers to the plugin (declared in its manifest and
+     * available here); call them with `service()`. Absent on older hosts.
+     */
+    services?: string[];
+    /** Learning progress of `self` (empty for board/settings). */
+    progress: Record<string, ProgressRecord>;
+    /** Plugin data of `self` (`null` values for board/settings). */
+    data: PluginData;
+    /** Last saved snapshot, only for the authority (resume). */
+    snapshot: unknown | null;
+}
+/**
+ * The session clock. `Date.now() + offsetMs` is the session time. RC4 adds pauses: the
+ * game time is `(pausedAt ?? sessionTime) - pausedMs` – it stands still while the host
+ * has paused the game (`pausedAt` = session time of the pause) and continues afterwards
+ * without the paused time (`pausedMs` = total of finished pauses).
+ */
+export interface SessionClock {
+    offsetMs: number;
+    pausedMs?: number;
+    pausedAt?: number | null;
+}
+export interface AnswerRecord {
+    /** Default: self. The authority may record for any player. */
+    playerId?: string;
+    itemId: string;
+    isCorrect: boolean;
+    confidence?: 1 | 2 | 3 | 4;
+    timeSpentMs?: number;
+    hintsUsed?: number;
+    isSkipped?: boolean;
+    /**
+     * RC4: what the player answered, in the `checkAnswer` format of the item type
+     * (choice IDs, text, numbers…). Lets teachers see which wrong answers were chosen.
+     */
+    answer?: unknown;
+    /**
+     * RC4: the item itself, required when `itemId` is not in the set (a generated item, e.g.
+     * from a service). It needs at least `id` (= `itemId`) and `type`; the answer fields may
+     * be left out. Such answers count for statistics (`skills`, `tags`), not for repetition.
+     */
+    item?: {
+        id: string;
+        type: string;
+        [key: string]: unknown;
+    };
+}
+export interface SessionResult {
+    /** Final score per player ID (in solo: the single player). */
+    scores?: Record<string, number>;
+    /** Short plain-text summary shown by the host. */
+    summary?: string;
+}
+export interface SettingsUpdate {
+    values: Record<string, unknown>;
+    valid: boolean;
+    message?: string;
+}
+export interface ResizeRequest {
+    height: number | 'auto';
+}
+export interface ErrorReport {
+    code: string;
+    message: string;
+    context?: Record<string, unknown>;
+}
+export interface OutgoingMessage {
+    /** `'all'` = every other instance. */
+    to: 'authority' | 'all' | Address[];
+    /** JSON-serializable. */
+    data: unknown;
+}
+export interface IncomingMessage {
+    from: Address;
+    data: unknown;
+    /** Session clock (ms). */
+    sentAt: number;
+}
+export type SessionEndReason = 'finished' | 'host_left' | 'kicked' | 'closed' | 'error';
+/** Methods the host exposes to the plugin (plugin → host). SPEC section 5. */
+export interface HostApi {
+    hello(handshake: Handshake): Promise<InitPayload>;
+    ready(): Promise<void>;
+    send(message: OutgoingMessage): Promise<void>;
+    saveSnapshot(snapshot: unknown): Promise<void>;
+    recordAnswer(answer: AnswerRecord): Promise<void>;
+    saveProgress(records: Record<string, ProgressRecord>): Promise<void>;
+    saveData(scope: DataScope, value: unknown): Promise<void>;
+    updateSettings(update: SettingsUpdate): Promise<void>;
+    getAsset(key: string, itemId?: string): Promise<Blob>;
+    end(result: SessionResult): Promise<void>;
+    resize(request: ResizeRequest): Promise<void>;
+    reportError(error: ErrorReport): Promise<void>;
+    exit(): Promise<void>;
+    /** RC4: calls a Memizy service (one of `InitPayload.services`); returns its JSON result. */
+    service(name: string, payload: unknown): Promise<unknown>;
+}
+/** Methods the plugin exposes to the host (host → plugin). SPEC section 7. */
+export interface PluginApi {
+    start(): Promise<void>;
+    deliver(message: IncomingMessage): Promise<void>;
+    playersChanged(players: Player[]): Promise<void>;
+    authorityChanged(status: {
+        connected: boolean;
+    }): Promise<void>;
+    setChanged(set: {
+        meta: OQSEMeta;
+        items: OQSEAnyItem[];
+    }): Promise<void>;
+    configChanged(config: Theme): Promise<void>;
+    /** The clock was corrected, or the game was paused / resumed (RC4). */
+    clockChanged(clock: SessionClock): Promise<void>;
+    sessionEnded(reason: SessionEndReason): Promise<void>;
+}
+export declare const HOST_API_METHODS: readonly ["hello", "ready", "send", "saveSnapshot", "recordAnswer", "saveProgress", "saveData", "updateSettings", "getAsset", "end", "resize", "reportError", "exit", "service"];
+export declare const PLUGIN_API_METHODS: readonly ["start", "deliver", "playersChanged", "authorityChanged", "setChanged", "configChanged", "clockChanged", "sessionEnded"];

package/dist/src/version.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Protocol version handling (SPEC section 4.3).
+ */
+/** The protocol version implemented by this package. */
+export declare const PROTOCOL_VERSION = "1.0";
+export interface ProtocolVersion {
+    major: number;
+    minor: number;
+}
+/** Parses a `MAJOR.MINOR` version. Returns `null` for anything else. */
+export declare function parseProtocolVersion(version: string): ProtocolVersion | null;
+/** Compares two `MAJOR.MINOR` versions (negative: a < b, 0: equal, positive: a > b). */
+export declare function compareProtocolVersions(a: string, b: string): number;
+/**
+ * The protocol versions a host supports: one version, or one per MAJOR it supports
+ * (e.g. `['1.4', '2.1']`, SPEC 4.3).
+ */
+export type HostProtocolVersions = string | readonly string[];
+/**
+ * Negotiates the version both sides use: the plugin's MAJOR (which the host must
+ * support), the lower MINOR. Returns `null` when the host does not support that MAJOR
+ * or a version is invalid.
+ */
+export declare function negotiateProtocolVersion(plugin: string, host: HostProtocolVersions): string | null;
+/**
+ * Checks before loading the iframe whether a host can run a plugin whose
+ * manifest requires `required` (SPEC 4.3): the host supports its MAJOR with a MINOR ≥
+ * the required one.
+ */
+export declare function isProtocolSupported(required: string, host?: HostProtocolVersions): boolean;

package/dist/types.cjs

@@ -0,0 +1 @@
+var e=`board`,t=`server`,n=[`hello`,`ready`,`send`,`saveSnapshot`,`recordAnswer`,`saveProgress`,`saveData`,`updateSettings`,`getAsset`,`end`,`resize`,`reportError`,`exit`,`service`],r=[`start`,`deliver`,`playersChanged`,`authorityChanged`,`setChanged`,`configChanged`,`clockChanged`,`sessionEnded`];exports.BOARD_ADDRESS=e,exports.HOST_API_METHODS=n,exports.PLUGIN_API_METHODS=r,exports.SERVER_ADDRESS=t;

package/dist/types.js

@@ -0,0 +1,28 @@
+//#region src/types.ts
+var e = "board", t = "server", n = [
+	"hello",
+	"ready",
+	"send",
+	"saveSnapshot",
+	"recordAnswer",
+	"saveProgress",
+	"saveData",
+	"updateSettings",
+	"getAsset",
+	"end",
+	"resize",
+	"reportError",
+	"exit",
+	"service"
+], r = [
+	"start",
+	"deliver",
+	"playersChanged",
+	"authorityChanged",
+	"setChanged",
+	"configChanged",
+	"clockChanged",
+	"sessionEnded"
+];
+//#endregion
+export { e as BOARD_ADDRESS, n as HOST_API_METHODS, r as PLUGIN_API_METHODS, t as SERVER_ADDRESS };

package/dist/version.cjs

@@ -0,0 +1 @@
+var e=`1.0`,t=/^(\d+)\.(\d+)$/;function n(e){let n=t.exec(e);return n?{major:Number(n[1]),minor:Number(n[2])}:null}function r(e,t){let r=n(e),i=n(t);if(!r||!i)throw Error(`Invalid protocol version: ${r?t:e}`);return r.major===i.major?r.minor-i.minor:r.major-i.major}function i(e,t){for(let r of typeof t==`string`?[t]:t){let t=n(r);if(t?.major===e)return t}return null}function a(e,t){let r=n(e),a=r&&i(r.major,t);return!r||!a?null:`${r.major}.${Math.min(r.minor,a.minor)}`}function o(e,t=`1.0`){let r=n(e),a=r&&i(r.major,t);return!!r&&!!a&&a.minor>=r.minor}exports.PROTOCOL_VERSION=e,exports.compareProtocolVersions=r,exports.isProtocolSupported=o,exports.negotiateProtocolVersion=a,exports.parseProtocolVersion=n;

package/dist/version.js

@@ -0,0 +1,31 @@
+//#region src/version.ts
+var e = "1.0", t = /^(\d+)\.(\d+)$/;
+function n(e) {
+	let n = t.exec(e);
+	return n ? {
+		major: Number(n[1]),
+		minor: Number(n[2])
+	} : null;
+}
+function r(e, t) {
+	let r = n(e), i = n(t);
+	if (!r || !i) throw Error(`Invalid protocol version: ${r ? t : e}`);
+	return r.major === i.major ? r.minor - i.minor : r.major - i.major;
+}
+function i(e, t) {
+	for (let r of typeof t == "string" ? [t] : t) {
+		let t = n(r);
+		if (t?.major === e) return t;
+	}
+	return null;
+}
+function a(e, t) {
+	let r = n(e), a = r && i(r.major, t);
+	return !r || !a ? null : `${r.major}.${Math.min(r.minor, a.minor)}`;
+}
+function o(e, t = "1.0") {
+	let r = n(e), a = r && i(r.major, t);
+	return !!r && !!a && a.minor >= r.minor;
+}
+//#endregion
+export { e as PROTOCOL_VERSION, r as compareProtocolVersions, o as isProtocolSupported, a as negotiateProtocolVersion, n as parseProtocolVersion };

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@memizy/protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc.5",
+  "description": "Memizy Plugin Protocol: types, Zod schemas and helpers shared by @memizy/plugin-sdk and @memizy/host-sdk.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/src/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "SPEC.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@memizy/oqse": "^1.0.0-rc.5",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "~6.0.2",
+    "vite": "^8.0.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.4"
+  },
+  "license": "MIT",
+  "author": "Memizy Team",
+  "keywords": [
+    "memizy",
+    "plugin",
+    "protocol",
+    "oqse",
+    "education"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memizy/memizy.git",
+    "directory": "packages/protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/memizy/memizy/issues"
+  },
+  "homepage": "https://github.com/memizy/memizy/tree/main/packages/protocol#readme"
+}