@memizy/host-sdk 0.0.0-stage → 1.0.0-rc.6

package/dist/src/session.d.ts

@@ -0,0 +1,248 @@
+import { AnswerRecord, HostApi, HostAs, Player, PluginApi, PluginRuntime, PluginView, SessionEndReason, SessionResult, HostConfig, SessionClock } from '@memizy/protocol';
+import { OQSEFile, ProgressRecord } from '@memizy/oqse';
+import { LearningAlgorithm } from './learning.js';
+import { HostStorage } from './storage.js';
+import { LoadedPlugin, PreparedSet } from './plugin.js';
+export interface SessionPlayer {
+    id: string;
+    name: string;
+    isHost?: boolean;
+}
+export interface SessionConfig {
+    plugin: LoadedPlugin;
+    /** The study set, loaded with `loadOQSEFile`. */
+    set: OQSEFile;
+    mode: 'solo' | 'multiplayer';
+    /** Multiplayer only: how the host takes part. */
+    hostAs?: HostAs;
+    /** Solo: exactly one player (default: a player called "Player"). Multiplayer: the roster. */
+    players?: SessionPlayer[];
+    /** Setting values (defaults are applied; invalid values throw). */
+    settings?: Record<string, unknown>;
+    storage?: HostStorage;
+    algorithm?: LearningAlgorithm;
+    /** Loader for assets that are not absolute URLs (e.g. files of an `.oqse` package). */
+    loadAsset?: (key: string, itemId: string | undefined) => Promise<Blob>;
+    /** Maps a player to the key of their stored progress and data (default: the player ID). */
+    userKeyFor?: (playerId: string) => string;
+    /** Language of the app (default `'en'`). */
+    locale?: string;
+    /** Theme of the app (default `'light'`). */
+    theme?: HostConfig['theme'];
+    sessionId?: string;
+    /**
+     * Seed of the display order of options, pairs… (SPEC 4.4; default: the session id).
+     * Pass the seed used for the relay bundle so all devices agree; `null` keeps the set's order.
+     */
+    shuffleSeed?: string | null;
+    host?: {
+        name: string;
+        version: string;
+    };
+    /** Max wait for all instances to be ready before the countdown (default 15 s). */
+    readyTimeoutMs?: number;
+    /** Countdown before the game starts in multiplayer (default 3 s; 0 = none). */
+    countdownMs?: number;
+    /**
+     * The session was already running (e.g. the host page was reloaded; pass the
+     * same `sessionId` and a persistent `storage`). The authority resumes from its
+     * last snapshot; without a snapshot the game starts again right away.
+     */
+    restore?: boolean;
+    /** When resuming: the pauses so far (from the `paused` events), so timers stay right. */
+    clock?: {
+        pausedMs?: number;
+        pausedAt?: number | null;
+    };
+    /**
+     * Memizy services this host offers (SPEC 5.3), by name. A plugin may call those it
+     * declares in `services`; payloads and results are JSON. Throw a `ProtocolError` to
+     * reject a call with a specific code.
+     */
+    services?: Record<string, ServiceHandler>;
+}
+/** Handles one service call. `playerId` is null on the board. */
+export type ServiceHandler = (payload: unknown, context: {
+    playerId: string | null;
+    address: string;
+    pluginId: string;
+    setId: string;
+}) => Promise<unknown>;
+export type SessionEvent = {
+    type: 'ready';
+    address: string;
+} | {
+    type: 'countdown';
+    secondsLeft: number;
+} | {
+    type: 'started';
+} | {
+    type: 'settings';
+    values: Record<string, unknown>;
+    valid: boolean;
+    message?: string;
+}
+/**
+ * A recorded answer. `record` is the updated learning progress (null for a generated item,
+ * which is not repeated); `skills` / `tags` come from the item (for statistics).
+ */
+ | {
+    type: 'answer';
+    playerId: string;
+    record: ProgressRecord | null;
+    answer: AnswerRecord;
+    generated: boolean;
+    skills: string[];
+    tags: string[];
+}
+/** The game reported its result (`end(result)`); the session itself ends with `end()`. */
+ | {
+    type: 'result';
+    result: SessionResult;
+} | {
+    type: 'players';
+    players: Player[];
+} | {
+    type: 'authority';
+    connected: boolean;
+} | {
+    type: 'traffic';
+    from: string;
+    to: string;
+    bytes: number;
+    data: unknown;
+} | {
+    type: 'rejected';
+    address: string;
+    method: string;
+    code: string;
+    message: string;
+} | {
+    type: 'pluginError';
+    address: string;
+    code: string;
+    message: string;
+    context?: Record<string, unknown>;
+}
+/** The host paused or resumed the game (store `clock` to resume a reloaded host). */
+ | {
+    type: 'paused';
+    paused: boolean;
+    clock: {
+        pausedMs: number;
+        pausedAt: number | null;
+    };
+};
+/** Creates the plugin side of an instance for a given host API (iframe + Penpal, or a direct connection in tests). */
+export type PluginEndpoint = (hostApi: HostApi) => PluginApi | Promise<PluginApi>;
+export interface SessionInstance {
+    readonly address: string;
+    readonly view: PluginView;
+    readonly hostApi: HostApi;
+}
+export declare class LocalSession {
+    readonly id: string;
+    readonly plugin: LoadedPlugin;
+    readonly runtime: PluginRuntime;
+    readonly mode: 'solo' | 'multiplayer';
+    readonly hostAs: HostAs | null;
+    readonly authority: string;
+    readonly prepared: PreparedSet;
+    private roster;
+    private settingValues;
+    private settingsOk;
+    private hostConfig;
+    private isStarted;
+    private isEnded;
+    /** Pauses of the game (game time = session time without them). */
+    private pauseState;
+    private readonly options;
+    private readonly storage;
+    private readonly algorithm;
+    private readonly instances;
+    private readonly listeners;
+    private authorityConnected;
+    private startPromise;
+    private resumeStartPending;
+    private pendingSnapshot;
+    /** The game has a result (`end(result)` or `end('finished')`): its snapshot is gone for good. */
+    private finished;
+    /** The authority called `end(result)`; later calls are ignored. */
+    private hasResult;
+    /** After the end, snapshots live only here: a reloaded authority still shows the end screen. */
+    private finishedSnapshot;
+    private snapshotTimer;
+    private readonly pendingData;
+    /** The players (the presenter is not one). Change them with `addPlayer`, `removePlayer`, `renamePlayer`, `setConnected`. */
+    get players(): readonly Player[];
+    /** Values of the settings (defaults applied; the plugin's own settings screen may change them in the lobby). */
+    get settings(): Readonly<Record<string, unknown>>;
+    /** Whether the settings are valid (the plugin's own settings screen reports it). */
+    get settingsValid(): boolean;
+    /** Language and theme of the app (change them with `setConfig`). */
+    get config(): Readonly<HostConfig>;
+    get started(): boolean;
+    get ended(): boolean;
+    constructor(config: SessionConfig);
+    on(listener: (event: SessionEvent) => void): () => void;
+    private emit;
+    /** The default view of an address in this session. */
+    viewOf(address: string): PluginView;
+    /** Addresses that have a game instance in this session (board and players). */
+    addresses(): string[];
+    /**
+     * Connects a plugin instance at `address` (a player ID, `"board"`, or `"settings"`
+     * for the lobby settings screen). An existing instance at the address is replaced.
+     */
+    connect(address: string, endpoint: PluginEndpoint, options?: {
+        onDispose?: () => void;
+    }): Promise<SessionInstance>;
+    /** Recreates the instance at `address` (like a browser reload or a reconnect). */
+    reload(address: string): Promise<SessionInstance>;
+    /** Removes the instance at `address` (the player stays in the roster). */
+    disconnect(address: string): void;
+    private disposeInstance;
+    getInstance(address: string): SessionInstance | undefined;
+    /**
+     * Multiplayer: waits until all connected game instances are ready (or the
+     * ready timeout passes), runs the countdown and starts the game on the
+     * authority (SPEC 3.3). Solo games start automatically when ready.
+     */
+    start(): Promise<void>;
+    private runStart;
+    addPlayer(player: SessionPlayer): void;
+    removePlayer(id: string): void;
+    renamePlayer(id: string, name: string): void;
+    /**
+     * Simulates a connection loss / recovery of an instance. Messages to and from a
+     * disconnected instance are dropped; for the authority, the others are told
+     * that the authority is unavailable (SPEC 6.1).
+     */
+    setConnected(address: string, connected: boolean): void;
+    /** Services the plugin declares and this host offers (SPEC 5.3). */
+    get services(): string[];
+    /** Whether the game is paused (the clock stands still on every device). */
+    get paused(): boolean;
+    /** The session clock as sent to the instances (host time; the relay adds each device's skew). */
+    get clock(): SessionClock;
+    /** Pauses the game: timers and countdowns stop, players cannot act (the SDK shows "Paused"). */
+    pause(): void;
+    /** Continues a paused game. */
+    resume(): void;
+    private broadcastClock;
+    setConfig(config: Partial<HostConfig>): void;
+    /** Ends the session for all instances (they stay mounted until the app removes them). */
+    end(reason?: SessionEndReason): Promise<void>;
+    private createHostApi;
+    private buildInit;
+    private userKey;
+    private deliver;
+    private broadcastPlayers;
+    private setAuthorityConnected;
+    private callPlugin;
+    /** Drops the pending snapshot and deletes the saved one; later saves are ignored. */
+    private discardSnapshot;
+    private flushSnapshot;
+    private pendingDataValue;
+    private flushData;
+}

package/dist/src/storage.d.ts

@@ -0,0 +1,27 @@
+import { ProgressRecord } from '@memizy/oqse';
+import { DataScope } from '@memizy/protocol';
+export interface HostStorage {
+    loadProgress(userKey: string, setId: string): Promise<Record<string, ProgressRecord>>;
+    /** Upserts the given records (other records stay). */
+    saveProgress(userKey: string, setId: string, records: Record<string, ProgressRecord>): Promise<void>;
+    /** `setId` is ignored for scope `plugin`. Returns `null` when nothing is saved. */
+    loadData(userKey: string, pluginId: string, scope: DataScope, setId: string): Promise<unknown>;
+    saveData(userKey: string, pluginId: string, scope: DataScope, setId: string, value: unknown): Promise<void>;
+    loadSnapshot(sessionId: string): Promise<unknown | null>;
+    saveSnapshot(sessionId: string, snapshot: unknown): Promise<void>;
+    /** Removes the snapshot of a finished game (optional; without it the snapshot stays). */
+    deleteSnapshot?(sessionId: string): Promise<void>;
+}
+/** In-memory storage (values are copied, like a real store would). */
+export declare class MemoryStorage implements HostStorage {
+    readonly progress: Map<string, Record<string, ProgressRecord>>;
+    readonly data: Map<string, unknown>;
+    readonly snapshots: Map<string, unknown>;
+    loadProgress(userKey: string, setId: string): Promise<Record<string, ProgressRecord>>;
+    saveProgress(userKey: string, setId: string, records: Record<string, ProgressRecord>): Promise<void>;
+    loadData(userKey: string, pluginId: string, scope: DataScope, setId: string): Promise<{} | null>;
+    saveData(userKey: string, pluginId: string, scope: DataScope, setId: string, value: unknown): Promise<void>;
+    loadSnapshot(sessionId: string): Promise<{} | null>;
+    saveSnapshot(sessionId: string, snapshot: unknown): Promise<void>;
+    deleteSnapshot(sessionId: string): Promise<void>;
+}

package/dist/src/version.d.ts

@@ -0,0 +1,2 @@
+/** The version of this package (filled in by the build; `0.0.0-dev` when run from source). */
+export declare const HOST_SDK_VERSION: string;

package/dist/storage.cjs

@@ -0,0 +1 @@
+var e=(e,t,n,r)=>JSON.stringify([e,t,n,n===`set`?r:null]),t=class{progress=new Map;data=new Map;snapshots=new Map;async loadProgress(e,t){return structuredClone(this.progress.get(`${e}|${t}`)??{})}async saveProgress(e,t,n){let r=`${e}|${t}`;this.progress.set(r,{...this.progress.get(r)??{},...structuredClone(n)})}async loadData(t,n,r,i){let a=this.data.get(e(t,n,r,i));return a===void 0?null:structuredClone(a)}async saveData(t,n,r,i,a){this.data.set(e(t,n,r,i),structuredClone(a))}async loadSnapshot(e){let t=this.snapshots.get(e);return t===void 0?null:structuredClone(t)}async saveSnapshot(e,t){this.snapshots.set(e,structuredClone(t))}async deleteSnapshot(e){this.snapshots.delete(e)}};exports.MemoryStorage=t;

package/dist/storage.js

@@ -0,0 +1,40 @@
+//#region src/storage.ts
+var e = (e, t, n, r) => JSON.stringify([
+	e,
+	t,
+	n,
+	n === "set" ? r : null
+]), t = class {
+	progress = /* @__PURE__ */ new Map();
+	data = /* @__PURE__ */ new Map();
+	snapshots = /* @__PURE__ */ new Map();
+	async loadProgress(e, t) {
+		return structuredClone(this.progress.get(`${e}|${t}`) ?? {});
+	}
+	async saveProgress(e, t, n) {
+		let r = `${e}|${t}`;
+		this.progress.set(r, {
+			...this.progress.get(r) ?? {},
+			...structuredClone(n)
+		});
+	}
+	async loadData(t, n, r, i) {
+		let a = this.data.get(e(t, n, r, i));
+		return a === void 0 ? null : structuredClone(a);
+	}
+	async saveData(t, n, r, i, a) {
+		this.data.set(e(t, n, r, i), structuredClone(a));
+	}
+	async loadSnapshot(e) {
+		let t = this.snapshots.get(e);
+		return t === void 0 ? null : structuredClone(t);
+	}
+	async saveSnapshot(e, t) {
+		this.snapshots.set(e, structuredClone(t));
+	}
+	async deleteSnapshot(e) {
+		this.snapshots.delete(e);
+	}
+};
+//#endregion
+export { t as MemoryStorage };

package/dist/version.cjs

@@ -0,0 +1 @@
+var e=`1.0.0-rc.6`;exports.HOST_SDK_VERSION=e;

package/dist/version.js

@@ -0,0 +1,4 @@
+//#region src/version.ts
+var e = "1.0.0-rc.6";
+//#endregion
+export { e as HOST_SDK_VERSION };

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@memizy/host-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc.6",
+  "description": "Run Memizy plugins: sandboxed iframes, protocol validation, sessions, storage hooks.",
+  "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",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && vite build && node ../../scripts/dts-extensions.mjs dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@memizy/oqse": "^1.0.0-rc.6",
+    "@memizy/protocol": "^1.0.0-rc.6",
+    "penpal": "^8.0.1"
+  },
+  "devDependencies": {
+    "@memizy/plugin-sdk": "^1.0.0-rc.6",
+    "@types/node": "^25.6.0",
+    "@types/ws": "^8",
+    "jsdom": "^30.1.2",
+    "typescript": "~6.0.2",
+    "vite": "^8.0.9",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.4",
+    "ws": "^8"
+  },
+  "license": "MIT",
+  "author": "Memizy Team",
+  "keywords": [
+    "memizy",
+    "plugin",
+    "host",
+    "sdk",
+    "multiplayer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memizy/memizy.git",
+    "directory": "packages/host-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/memizy/memizy/issues"
+  },
+  "homepage": "https://github.com/memizy/memizy/tree/main/packages/host-sdk#readme"
+}