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

package/dist/src/types.d.ts

@@ -1,11 +1,13 @@
 import { OQSEAnyItem, OQSEMeta, ProgressRecord } from '@memizy/oqse';
-import { HostAs, PluginView } from './pluginRuntime';
-/** Address of an instance: a player ID, `"board"`; `"server"` is reserved. */
+import { HostAs, PluginView } from './pluginRuntime.js';
+/** Address of an instance: a player ID, `"board"`, `"settings"` (`SETTINGS_ADDRESS`); `"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";
+/** Address of the plugin's own settings screen in the lobby (view `settings`). */
+export declare const SETTINGS_ADDRESS = "settings";
 export type SessionMode = 'solo' | 'multiplayer';
 export interface Player {
     id: string;
@@ -39,7 +41,8 @@ export interface Handshake {
     };
     features: string[];
 }
-export interface Theme {
+/** Language and theme of the app (`InitPayload.config`, `configChanged`). */
+export interface HostConfig {
     locale: string;
     theme: 'light' | 'dark';
 }
@@ -68,34 +71,38 @@ export interface InitPayload {
     };
     /** Values for every declared setting (defaults applied). */
     settings: Record<string, unknown>;
-    config: Theme;
+    config: HostConfig;
     /** 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[];
+    /** Memizy services this host offers to the plugin (declared in its manifest and available here); call them with `service()`. */
+    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;
+    /**
+     * Only for the authority: the secret seed of the game's random numbers (at least 128 bits,
+     * e.g. 32 hex digits). Other instances never get it (SPEC 4.2).
+     */
+    seed?: string;
 }
 /**
- * The session clock. `Date.now() + offsetMs` is the session time. RC4 adds pauses: the
+ * The session clock. `Date.now() + offsetMs` is the session time. 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;
+    /** Total length of finished pauses (ms). */
+    pausedMs: number;
+    /** Session time when the current pause started, or `null` while the game runs. */
+    pausedAt: number | null;
 }
 export interface AnswerRecord {
-    /** Default: self. The authority may record for any player. */
+    /** Default: self (the authority as a player); required when the board records. Only the authority records (SPEC 5). */
     playerId?: string;
     itemId: string;
     isCorrect: boolean;
@@ -104,12 +111,17 @@ export interface AnswerRecord {
     hintsUsed?: number;
     isSkipped?: boolean;
     /**
-     * RC4: what the player answered, in the `checkAnswer` format of the item type
+     * Partial credit between 0 and 1 (e.g. 2 of 3 correct pairs = 0.67), for items that allow
+     * it (OQSE `pedagogy.partialCredit`). `isCorrect` stays the outcome used for repetition.
+     */
+    score?: number;
+    /**
+     * 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.
+     * 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.
      */
@@ -130,9 +142,6 @@ export interface SettingsUpdate {
     valid: boolean;
     message?: string;
 }
-export interface ResizeRequest {
-    height: number | 'auto';
-}
 export interface ErrorReport {
     code: string;
     message: string;
@@ -150,7 +159,7 @@ export interface IncomingMessage {
     /** Session clock (ms). */
     sentAt: number;
 }
-export type SessionEndReason = 'finished' | 'host_left' | 'kicked' | 'closed' | 'error';
+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>;
@@ -158,15 +167,12 @@ export interface HostApi {
     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. */
+    /** 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. */
@@ -177,14 +183,10 @@ export interface PluginApi {
     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). */
+    configChanged(config: HostConfig): Promise<void>;
+    /** The clock was corrected, or the game was paused / resumed. */
     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"];
+export declare const HOST_API_METHODS: readonly ["hello", "ready", "send", "saveSnapshot", "recordAnswer", "saveData", "updateSettings", "getAsset", "end", "reportError", "service"];
+export declare const PLUGIN_API_METHODS: readonly ["start", "deliver", "playersChanged", "authorityChanged", "configChanged", "clockChanged", "sessionEnded"];

package/dist/types.cjs

@@ -1 +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;
+var e=`board`,t=`server`,n=`settings`,r=[`hello`,`ready`,`send`,`saveSnapshot`,`recordAnswer`,`saveData`,`updateSettings`,`getAsset`,`end`,`reportError`,`service`],i=[`start`,`deliver`,`playersChanged`,`authorityChanged`,`configChanged`,`clockChanged`,`sessionEnded`];exports.BOARD_ADDRESS=e,exports.HOST_API_METHODS=r,exports.PLUGIN_API_METHODS=i,exports.SERVER_ADDRESS=t,exports.SETTINGS_ADDRESS=n;

package/dist/types.js

@@ -1,28 +1,24 @@
 //#region src/types.ts
-var e = "board", t = "server", n = [
+var e = "board", t = "server", n = "settings", r = [
 	"hello",
 	"ready",
 	"send",
 	"saveSnapshot",
 	"recordAnswer",
-	"saveProgress",
 	"saveData",
 	"updateSettings",
 	"getAsset",
 	"end",
-	"resize",
 	"reportError",
-	"exit",
 	"service"
-], r = [
+], i = [
 	"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 };
+export { e as BOARD_ADDRESS, r as HOST_API_METHODS, i as PLUGIN_API_METHODS, t as SERVER_ADDRESS, n as SETTINGS_ADDRESS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memizy/protocol",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "description": "Memizy Plugin Protocol: types, Zod schemas and helpers shared by @memizy/plugin-sdk and @memizy/host-sdk.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,21 +12,29 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./internal": {
+      "types": "./dist/src/internal.d.ts",
+      "import": "./dist/internal.js",
+      "require": "./dist/internal.cjs"
     }
   },
   "files": [
     "dist",
     "SPEC.md",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "scripts": {
-    "build": "tsc --noEmit && vite build",
+    "build": "tsc --noEmit && vite build && node ../../scripts/dts-extensions.mjs dist",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@memizy/oqse": "^1.0.0-rc.5",
+    "@memizy/oqse": "^1.0.0-rc.7",
     "zod": "^4.3.6"
   },
   "devDependencies": {