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

package/dist/session.js

@@ -0,0 +1,530 @@
+import { prepareSetForPlugin as e } from "./plugin.js";
+import { leitner as t } from "./learning.js";
+import { MemoryStorage as n } from "./storage.js";
+import { BOARD_ADDRESS as r, LIMITS as i, PROTOCOL_VERSION as a, ProtocolError as o, RateLimiter as s, assertJsonWithin as c, negotiateProtocolVersion as l, parseHostCall as u, resolveSettings as d, toProtocolError as f } from "@memizy/protocol";
+import { resolveAsset as p } from "@memizy/oqse";
+//#region src/session.ts
+var m = "settings";
+function h(e) {
+	try {
+		return structuredClone(e);
+	} catch {
+		return JSON.parse(JSON.stringify(e));
+	}
+}
+var g = class {
+	id;
+	plugin;
+	runtime;
+	mode;
+	hostAs;
+	authority;
+	prepared;
+	players;
+	settings;
+	settingsValid = !0;
+	config;
+	started = !1;
+	ended = !1;
+	pauseState = {
+		pausedMs: 0,
+		pausedAt: null
+	};
+	options;
+	storage;
+	algorithm;
+	instances = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	authorityConnected = !0;
+	startPromise = null;
+	resumeStartPending = !1;
+	pendingSnapshot = void 0;
+	snapshotTimer;
+	pendingData = /* @__PURE__ */ new Map();
+	constructor(i) {
+		if (this.options = i, this.id = i.sessionId ?? `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`, this.plugin = i.plugin, this.runtime = i.plugin.runtime, this.mode = i.mode, this.storage = i.storage ?? new n(), this.algorithm = i.algorithm ?? t, this.config = {
+			locale: i.config?.locale ?? "cs",
+			theme: i.config?.theme ?? "light"
+		}, i.mode === "solo") {
+			if (!this.runtime.solo) throw Error("The plugin does not support solo mode.");
+			this.hostAs = null;
+		} else {
+			if (!this.runtime.multiplayer) throw Error("The plugin does not support multiplayer.");
+			let e = i.hostAs ?? this.runtime.multiplayer.hostAs[0];
+			if (!this.runtime.multiplayer.hostAs.includes(e)) throw Error(`The plugin does not support hostAs "${e}".`);
+			this.hostAs = e;
+		}
+		let a = i.players ?? (i.mode === "solo" ? [{
+			id: "player",
+			name: "Player",
+			isHost: !0
+		}] : []);
+		if (i.mode === "solo" && a.length !== 1) throw Error("A solo session has exactly one player.");
+		if (new Set(a.map((e) => e.id)).size !== a.length) throw Error("Player IDs must be unique.");
+		if (a.some((e) => e.id === r || e.id === "settings" || e.id === "server")) throw Error("Player IDs \"board\", \"settings\" and \"server\" are reserved.");
+		if (this.players = a.map((e) => ({
+			id: e.id,
+			name: e.name,
+			isHost: i.mode === "solo" ? !0 : e.isHost ?? !1,
+			connected: !0
+		})), i.mode === "solo") this.authority = this.players[0].id;
+		else if (this.hostAs === "presenter") this.authority = r;
+		else {
+			let e = this.players.find((e) => e.isHost);
+			if (!e) throw Error("With hostAs \"player\", one player must have isHost: true.");
+			this.authority = e.id;
+		}
+		let o = d(this.runtime.settings, i.settings ?? {});
+		if (o.errors.length > 0) throw Error(`Invalid settings: ${o.errors.join("; ")}`);
+		this.settings = o.values;
+		let s = i.shuffleSeed === null ? void 0 : i.shuffleSeed ?? this.id;
+		this.prepared = e(h(i.set), i.plugin.manifest, { seed: s }), i.resume && (this.started = !0, this.resumeStartPending = !0), i.clock && (this.pauseState = {
+			pausedMs: i.clock.pausedMs ?? 0,
+			pausedAt: i.clock.pausedAt ?? null
+		});
+	}
+	on(e) {
+		return this.listeners.add(e), () => this.listeners.delete(e);
+	}
+	emit(e) {
+		for (let t of this.listeners) try {
+			t(e);
+		} catch (e) {
+			console.error("[memizy host] session listener failed:", e);
+		}
+	}
+	viewOf(e) {
+		return e === "settings" ? "settings" : this.mode === "solo" ? "solo" : e === r ? "board" : "controller";
+	}
+	addresses() {
+		return [...this.hostAs === "presenter" ? [r] : [], ...this.players.map((e) => e.id)];
+	}
+	async connect(e, t, n = {}) {
+		let r = this.viewOf(e);
+		if (r === "settings") {
+			if (!this.runtime.multiplayer || !this.runtime.settingsScreen) throw Error("The plugin has no settings screen (settingsScreen).");
+			if (this.started) throw Error("The settings screen is only available before the game starts.");
+		} else if (!this.addresses().includes(e)) throw Error(`Unknown address "${e}" in this session.`);
+		if (this.ended) throw Error("The session has ended.");
+		this.disposeInstance(e);
+		let a = {
+			address: e,
+			view: r,
+			hostApi: void 0,
+			endpoint: t,
+			onDispose: n.onDispose,
+			plugin: null,
+			ready: !1,
+			connected: !0,
+			disposed: !1,
+			resumed: !1,
+			limiter: new s(i.messagesPerSecond, i.messageBurst),
+			serviceLimiter: new s(i.servicesPerMinute / 60, 10)
+		};
+		a.hostApi = this.createHostApi(a), this.instances.set(e, a), e === this.authority && this.started && this.setAuthorityConnected(!1);
+		try {
+			a.plugin = await t(a.hostApi);
+		} catch (e) {
+			if (a.disposed) return a;
+			throw e;
+		}
+		return a;
+	}
+	async reload(e) {
+		let t = this.instances.get(e);
+		if (!t) throw Error(`No instance at "${e}".`);
+		return e === this.authority && await this.flushSnapshot(), this.connect(e, t.endpoint, { onDispose: t.onDispose });
+	}
+	disconnect(e) {
+		this.disposeInstance(e), e === this.authority && this.started && this.setAuthorityConnected(!1);
+	}
+	disposeInstance(e) {
+		let t = this.instances.get(e);
+		if (t) {
+			t.disposed = !0, this.instances.delete(e);
+			try {
+				t.onDispose?.();
+			} catch (e) {
+				console.warn("[memizy host] dispose failed:", e);
+			}
+		}
+	}
+	getInstance(e) {
+		return this.instances.get(e);
+	}
+	start() {
+		if (this.mode === "solo" || this.started && !this.startPromise) return Promise.resolve();
+		if (!this.settingsValid) return Promise.reject(/* @__PURE__ */ Error("The settings are not valid."));
+		let e = this.players.length, t = this.runtime.multiplayer.players;
+		return e < t.min || e > t.max ? Promise.reject(/* @__PURE__ */ Error(`This plugin needs ${t.min}–${t.max} players (now ${e}).`)) : (this.startPromise ??= this.runStart(), this.startPromise);
+	}
+	async runStart() {
+		this.disposeInstance(m);
+		let e = Date.now() + (this.options.readyTimeoutMs ?? 15e3), t = () => [...this.instances.values()].every((e) => e.ready), n = () => this.instances.get(this.authority)?.ready === !0;
+		for (; !(t() && n()) && (Date.now() < e || !n());) {
+			if (this.ended) return;
+			await _(25);
+		}
+		let r = this.options.countdownMs ?? 3e3;
+		for (let e = Math.ceil(r / 1e3); e > 0; e--) this.emit({
+			type: "countdown",
+			secondsLeft: e
+		}), await _(Math.min(1e3, r - (Math.ceil(r / 1e3) - e) * 1e3));
+		this.ended || (this.started = !0, this.emit({ type: "started" }), await this.callPlugin(this.authority, (e) => e.start()));
+	}
+	addPlayer(e) {
+		if (this.mode === "solo") throw Error("Players cannot join a solo session.");
+		if (this.players.some((t) => t.id === e.id) || [
+			r,
+			"settings",
+			"server"
+		].includes(e.id)) throw Error(`Player ID "${e.id}" is already used or reserved.`);
+		if (this.started && !this.runtime.multiplayer.lateJoin) throw Error("This game does not allow joining after the start.");
+		if (this.players.length >= this.runtime.multiplayer.players.max) throw Error("The game is full.");
+		this.players = [...this.players, {
+			id: e.id,
+			name: e.name,
+			isHost: !1,
+			connected: !0
+		}], this.broadcastPlayers();
+	}
+	removePlayer(e) {
+		if (e === this.authority) throw Error("The host cannot be removed.");
+		this.disposeInstance(e), this.players = this.players.filter((t) => t.id !== e), this.broadcastPlayers();
+	}
+	renamePlayer(e, t) {
+		this.players = this.players.map((n) => n.id === e ? {
+			...n,
+			name: t
+		} : n), this.broadcastPlayers();
+	}
+	setConnected(e, t) {
+		let n = this.instances.get(e);
+		n && (n.connected = t), this.players.some((t) => t.id === e) && (this.players = this.players.map((n) => n.id === e ? {
+			...n,
+			connected: t
+		} : n), this.broadcastPlayers()), e === this.authority ? this.setAuthorityConnected(t) : t && n && this.callPlugin(e, (e) => e.authorityChanged({ connected: !0 }));
+	}
+	get services() {
+		return this.runtime.services.filter((e) => typeof this.options.services?.[e] == "function");
+	}
+	get paused() {
+		return this.pauseState.pausedAt !== null;
+	}
+	get clock() {
+		return {
+			offsetMs: 0,
+			...this.pauseState
+		};
+	}
+	pause() {
+		!this.started || this.ended || this.paused || (this.pauseState = {
+			...this.pauseState,
+			pausedAt: Date.now()
+		}, this.broadcastClock());
+	}
+	resume() {
+		this.paused && (this.pauseState = {
+			pausedMs: this.pauseState.pausedMs + Math.max(0, Date.now() - this.pauseState.pausedAt),
+			pausedAt: null
+		}, this.broadcastClock());
+	}
+	broadcastClock() {
+		let e = this.clock;
+		for (let t of this.instances.keys()) this.callPlugin(t, (t) => t.clockChanged(e));
+		this.emit({
+			type: "paused",
+			paused: this.paused,
+			clock: { ...this.pauseState }
+		});
+	}
+	setConfig(e) {
+		this.config = {
+			...this.config,
+			...e
+		};
+		for (let e of this.instances.keys()) this.callPlugin(e, (e) => e.configChanged(this.config));
+	}
+	async end(e = "closed") {
+		this.ended || (this.ended = !0, await this.flushSnapshot(), await this.flushData(), await Promise.all([...this.instances.keys()].map((t) => this.callPlugin(t, (t) => t.sessionEnded(e)))));
+	}
+	createHostApi(e) {
+		let t = (t, n) => (async () => {
+			if (e.disposed) throw new o("SESSION_ENDED", "This instance has been closed.");
+			if (this.ended && t !== "reportError") throw new o("SESSION_ENDED", "The session has ended.");
+			return n();
+		})().catch((n) => {
+			let r = f(n);
+			throw this.emit({
+				type: "rejected",
+				address: e.address,
+				method: t,
+				code: r.code,
+				message: r.detail
+			}), r;
+		}), n = () => e.view === "solo" || e.view === "controller", r = (t, n) => {
+			if (!n) throw new o("NOT_ALLOWED_IN_VIEW", `${t} is not available in view "${e.view}".`);
+		}, s = (t) => {
+			if (e.address !== this.authority) throw new o("NOT_AUTHORITY", `${t} may only be called by the authority.`);
+		};
+		return {
+			hello: (...n) => t("hello", async () => {
+				let [t] = u("hello", n), r = l(t.protocol, a);
+				if (!r) throw new o("UNSUPPORTED_PROTOCOL", `The plugin speaks protocol ${t.protocol}; this host supports ${a}.`);
+				return t.plugin.id !== this.plugin.manifest.id && this.emit({
+					type: "pluginError",
+					address: e.address,
+					code: "PLUGIN_ID_MISMATCH",
+					message: `The SDK reports plugin id "${t.plugin.id}", the manifest says "${this.plugin.manifest.id}".`
+				}), this.buildInit(e, r);
+			}),
+			ready: (...n) => t("ready", () => {
+				u("ready", n), !e.ready && (e.ready = !0, this.emit({
+					type: "ready",
+					address: e.address
+				}), e.address === this.authority && (this.mode === "solo" && !this.started && !e.resumed ? (this.started = !0, this.emit({ type: "started" }), this.callPlugin(e.address, (e) => e.start())) : this.started && (this.resumeStartPending && (this.resumeStartPending = !1, e.resumed || this.callPlugin(e.address, (e) => e.start())), this.setAuthorityConnected(!0))));
+			}),
+			send: (...n) => t("send", () => {
+				let [t] = u("send", n);
+				r("send", e.view !== "settings");
+				let a = c(t.data, i.messageBytes, "MESSAGE_TOO_LARGE", "message"), s = e.address === this.authority ? 1 / Math.max(1, this.instances.size - 1) : 1;
+				if (!e.limiter.tryTake(s)) throw new o("RATE_LIMITED", `More than ${i.messagesPerSecond} messages per second.`);
+				if (!e.connected) return;
+				if (t.to === "authority") {
+					let n = this.instances.get(this.authority);
+					if (!n || !n.connected || !this.authorityConnected) throw new o("AUTHORITY_UNAVAILABLE", "The host is not reachable right now.");
+					this.deliver(e.address, this.authority, t.data, a);
+					return;
+				}
+				let l = t.to === "all" ? [...this.instances.keys()].filter((t) => t !== e.address && t !== "settings") : t.to.filter((e) => e !== m);
+				for (let n of l) this.deliver(e.address, n, t.data, a);
+			}),
+			saveSnapshot: (...e) => t("saveSnapshot", () => {
+				let [t] = u("saveSnapshot", e);
+				s("saveSnapshot"), c(t, i.snapshotBytes, "SNAPSHOT_TOO_LARGE", "snapshot"), this.pendingSnapshot = structuredClone(t), this.snapshotTimer ??= setTimeout(() => void this.flushSnapshot(), 1e3 / i.snapshotsPerSecond);
+			}),
+			recordAnswer: (...n) => t("recordAnswer", async () => {
+				let [t] = u("recordAnswer", n), r = this.players.some((t) => t.id === e.address) ? e.address : null, a = t.playerId ?? r;
+				if (!a) throw new o("INVALID_ARGUMENT", "recordAnswer needs a playerId on the board.");
+				if (a !== r && s("recordAnswer for another player"), !this.players.some((e) => e.id === a)) throw new o("INVALID_ARGUMENT", `Unknown player "${a}".`);
+				t.answer !== void 0 && c(t.answer, i.answerBytes, "DATA_TOO_LARGE", "answer");
+				let l = this.prepared.set.items.find((e) => e.id === t.itemId), d = (e) => Array.isArray(e) ? e.filter((e) => typeof e == "string") : [];
+				if (!l) {
+					if (!t.item) throw new o("INVALID_ARGUMENT", `Unknown item "${t.itemId}" (attach the item for a generated one).`);
+					c(t.item, i.generatedItemBytes, "DATA_TOO_LARGE", "item"), this.emit({
+						type: "answer",
+						playerId: a,
+						record: null,
+						answer: t,
+						generated: !0,
+						skills: d(t.item.skills),
+						tags: d(t.item.tags)
+					});
+					return;
+				}
+				let f = this.userKey(a), p = this.prepared.set.meta.id, m = await this.storage.loadProgress(f, p), { item: h, ...g } = t, _ = this.algorithm.apply(m[t.itemId], g, /* @__PURE__ */ new Date());
+				await this.storage.saveProgress(f, p, { [t.itemId]: _ }), this.emit({
+					type: "answer",
+					playerId: a,
+					record: _,
+					answer: g,
+					generated: !1,
+					skills: d(l.skills),
+					tags: d(l.tags)
+				});
+			}),
+			saveProgress: (...i) => t("saveProgress", async () => {
+				let [t] = u("saveProgress", i);
+				r("saveProgress", n());
+				let a = new Set(this.prepared.set.items.map((e) => e.id)), s = Object.keys(t).filter((e) => !a.has(e));
+				if (s.length > 0) throw new o("INVALID_ARGUMENT", `Unknown items: ${s.join(", ")}.`);
+				await this.storage.saveProgress(this.userKey(e.address), this.prepared.set.meta.id, t);
+			}),
+			saveData: (...a) => t("saveData", () => {
+				let [t, o] = u("saveData", a);
+				r("saveData", n()), c(o, i.dataBytes, "DATA_TOO_LARGE", `plugin data (${t})`);
+				let s = `${e.address}|${t}`, l = this.pendingData.get(s);
+				if (l) l.value = structuredClone(o);
+				else {
+					let n = {
+						playerId: e.address,
+						scope: t,
+						value: structuredClone(o),
+						timer: setTimeout(() => void this.flushData(s), 1e3 / i.dataWritesPerSecond)
+					};
+					this.pendingData.set(s, n);
+				}
+			}),
+			updateSettings: (...n) => t("updateSettings", () => {
+				let [t] = u("updateSettings", n);
+				r("updateSettings", e.view === "settings");
+				let { values: i, errors: a } = d(this.runtime.settings, t.values);
+				this.settings = i, this.settingsValid = t.valid && a.length === 0;
+				let o = t.message ?? a[0];
+				this.emit({
+					type: "settings",
+					values: i,
+					valid: this.settingsValid,
+					...o && { message: o }
+				});
+			}),
+			getAsset: (...e) => t("getAsset", async () => {
+				let [t, n] = u("getAsset", e), r = n ? this.options.set.items.find((e) => e.id === n) : void 0, i = p(t, r, this.options.set.meta);
+				if (!i) throw new o("ASSET_NOT_FOUND", `Asset "${t}" does not exist.`);
+				if (this.options.loadAsset) return this.options.loadAsset(t, n);
+				if (/^https?:/i.test(i.value)) {
+					let e = await fetch(i.value);
+					if (e.ok) return e.blob();
+				}
+				throw new o("ASSET_NOT_FOUND", `Asset "${t}" cannot be loaded by this host.`);
+			}),
+			end: (...e) => t("end", async () => {
+				let [t] = u("end", e);
+				s("end"), this.emit({
+					type: "ended",
+					result: t
+				});
+			}),
+			resize: (...n) => t("resize", () => {
+				let [t] = u("resize", n);
+				this.emit({
+					type: "resize",
+					address: e.address,
+					height: t.height
+				});
+			}),
+			reportError: (...n) => t("reportError", () => {
+				let [t] = u("reportError", n);
+				this.emit({
+					type: "pluginError",
+					address: e.address,
+					code: t.code,
+					message: t.message,
+					...t.context && { context: t.context }
+				});
+			}),
+			exit: (...n) => t("exit", () => {
+				u("exit", n), this.emit({
+					type: "exit",
+					address: e.address
+				});
+			}),
+			service: (...n) => t("service", async () => {
+				let [t, r] = u("service", n), a = this.services.includes(t) ? this.options.services[t] : void 0;
+				if (!a) throw new o("SERVICE_UNAVAILABLE", `Service "${t}" is not available here (declare it in the manifest "services"; this host offers: ${this.services.join(", ") || "none"}).`);
+				if (c(r, i.serviceBytes, "MESSAGE_TOO_LARGE", `service ${t} request`), !e.serviceLimiter.tryTake()) throw new o("RATE_LIMITED", `More than ${i.servicesPerMinute} service calls per minute.`);
+				let s = this.players.some((t) => t.id === e.address) ? e.address : null, l = await a(h(r), {
+					playerId: s,
+					address: e.address,
+					pluginId: this.plugin.manifest.id,
+					setId: this.prepared.set.meta.id
+				});
+				return c(l ?? null, i.messageBytes * 4, "MESSAGE_TOO_LARGE", `service ${t} result`), h(l ?? null);
+			})
+		};
+	}
+	async buildInit(e, t) {
+		let n = e.view === "solo" || e.view === "controller", r = this.prepared.set.meta.id, i = n ? this.userKey(e.address) : null, a = this.plugin.manifest.id;
+		e.address === this.authority && await this.flushSnapshot();
+		let o = e.address === this.authority ? await this.storage.loadSnapshot(this.id) : null;
+		return e.resumed = o !== null, {
+			protocol: t,
+			host: this.options.host ?? {
+				name: "@memizy/host-sdk",
+				version: "1.0.0-rc.4"
+			},
+			oqseVersion: "1.0",
+			features: [],
+			session: {
+				id: this.id,
+				mode: this.mode,
+				hostAs: this.hostAs,
+				view: e.view,
+				self: e.address,
+				authority: this.authority,
+				lateJoin: this.started && e.view !== "settings"
+			},
+			players: this.players,
+			set: structuredClone(this.mode === "multiplayer" && e.address !== this.authority ? this.prepared.publicSet : this.prepared.set),
+			settings: { ...this.settings },
+			config: this.config,
+			clock: this.clock,
+			services: this.services,
+			progress: i ? await this.storage.loadProgress(i, r) : {},
+			data: i ? {
+				plugin: this.pendingDataValue(e.address, "plugin") ?? await this.storage.loadData(i, a, "plugin", r) ?? null,
+				set: this.pendingDataValue(e.address, "set") ?? await this.storage.loadData(i, a, "set", r) ?? null
+			} : {
+				plugin: null,
+				set: null
+			},
+			snapshot: o
+		};
+	}
+	userKey(e) {
+		return this.options.userKeyFor?.(e) ?? e;
+	}
+	deliver(e, t, n, r) {
+		let i = this.instances.get(t);
+		if (!i || !i.connected || !i.plugin) return;
+		this.emit({
+			type: "traffic",
+			from: e,
+			to: t,
+			bytes: r,
+			data: n
+		});
+		let a = structuredClone(n);
+		setTimeout(() => void this.callPlugin(t, (t) => t.deliver({
+			from: e,
+			data: a,
+			sentAt: Date.now()
+		})), 0);
+	}
+	broadcastPlayers() {
+		this.emit({
+			type: "players",
+			players: this.players
+		});
+		for (let e of this.instances.keys()) this.callPlugin(e, (e) => e.playersChanged(this.players));
+	}
+	setAuthorityConnected(e) {
+		if (this.authorityConnected !== e) {
+			this.authorityConnected = e, this.emit({
+				type: "authority",
+				connected: e
+			});
+			for (let t of this.instances.keys()) t !== this.authority && t !== "settings" && this.callPlugin(t, (t) => t.authorityChanged({ connected: e }));
+		}
+	}
+	async callPlugin(e, t) {
+		let n = this.instances.get(e);
+		if (n?.plugin && !n.disposed) try {
+			await t(n.plugin);
+		} catch (t) {
+			this.emit({
+				type: "pluginError",
+				address: e,
+				code: "PLUGIN_CALL_FAILED",
+				message: f(t).detail
+			});
+		}
+	}
+	async flushSnapshot() {
+		if (clearTimeout(this.snapshotTimer), this.snapshotTimer = void 0, this.pendingSnapshot === void 0) return;
+		let e = this.pendingSnapshot;
+		this.pendingSnapshot = void 0, await this.storage.saveSnapshot(this.id, e);
+	}
+	pendingDataValue(e, t) {
+		return this.pendingData.get(`${e}|${t}`)?.value;
+	}
+	async flushData(e) {
+		let t = e ? [[e, this.pendingData.get(e)]] : [...this.pendingData.entries()];
+		for (let [e, n] of t) n && (clearTimeout(n.timer), this.pendingData.delete(e), await this.storage.saveData(this.userKey(n.playerId), this.plugin.manifest.id, n.scope, this.prepared.set.meta.id, n.value));
+	}
+};
+function _(e) {
+	return new Promise((t) => setTimeout(t, Math.max(0, e)));
+}
+//#endregion
+export { g as LocalSession, m as SETTINGS_ADDRESS };

package/dist/src/frame.d.ts

@@ -0,0 +1,38 @@
+import { HostApi, PluginApi } from '@memizy/protocol';
+import { LocalSession, SessionInstance } from './session';
+/** Never add `allow-same-origin`: the plugin must not reach the app's origin. */
+export declare const PLUGIN_SANDBOX = "allow-scripts allow-forms allow-modals allow-pointer-lock";
+export interface MountOptions {
+    /** Text overrides (default: Czech or English by the session locale). */
+    texts?: {
+        waitingForHost?: string;
+        countdown?: (seconds: number) => string;
+    };
+    /** Show the built-in overlays (default `true`). */
+    overlays?: boolean;
+}
+export interface MountedPlugin {
+    readonly instance: SessionInstance;
+    readonly iframe: HTMLIFrameElement;
+    /** Removes the iframe and disconnects the instance. */
+    unmount(): void;
+}
+export interface PluginFrame {
+    readonly iframe: HTMLIFrameElement;
+    /** Resolves when the plugin has connected (Penpal handshake). */
+    readonly plugin: Promise<PluginApi>;
+    /** Closes the connection (the caller removes the iframe). */
+    destroy(): void;
+}
+/**
+ * Creates a sandboxed iframe with the plugin HTML and connects it to `hostApi`.
+ * The iframe must be inserted into the document by the caller (right away).
+ * The plugin reaches only what its manifest declares (SPEC 8.4): a Content Security
+ * Policy limits network requests, `allow` grants the declared devices.
+ */
+export declare function createPluginFrame(html: string, title: string, hostApi: HostApi, doc?: Document): PluginFrame;
+/**
+ * Mounts the session's plugin for `address` into `container` and connects it.
+ * Calling it again for the same address replaces the instance (reload).
+ */
+export declare function mountPlugin(session: LocalSession, address: string, container: HTMLElement, options?: MountOptions): Promise<MountedPlugin>;

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @memizy/host-sdk – run Memizy plugins: load and validate plugins, sandboxed
+ * iframes, protocol validation and limits, sessions, storage and learning hooks.
+ * Protocol: @memizy/protocol (SPEC.md).
+ */
+export * from './plugin';
+export * from './session';
+export * from './frame';
+export * from './storage';
+export * from './learning';
+export * from './relay/socket';
+export * from './relay/messages';
+export * from './relay/host';
+export * from './relay/player';

package/dist/src/learning.d.ts

@@ -0,0 +1,14 @@
+import { ProgressRecord } from '@memizy/oqse';
+import { AnswerRecord } from '@memizy/protocol';
+export interface LearningAlgorithm {
+    /** OQSEP `meta.algorithm` identifier. */
+    id: string;
+    apply(previous: ProgressRecord | undefined, answer: AnswerRecord, now: Date): ProgressRecord;
+}
+/** Days until the next review per Leitner bucket (index = bucket). */
+export declare const LEITNER_INTERVAL_DAYS: readonly [0, 1, 3, 7, 21];
+/**
+ * Leitner boxes: a correct answer moves the item one bucket up (max 4),
+ * a wrong answer back to bucket 1. Skipped answers do not change the bucket.
+ */
+export declare const leitner: LearningAlgorithm;

package/dist/src/plugin.d.ts

@@ -0,0 +1,51 @@
+import { PluginManifest, PluginRuntime } from '@memizy/protocol';
+import { CompatibilityReport, OQSEFile, OQSEAnyItem, OQSEMeta } from '@memizy/oqse';
+export interface LoadedPlugin {
+    /** The plugin HTML (rendered with `srcdoc`). */
+    html: string;
+    manifest: PluginManifest;
+    runtime: PluginRuntime;
+}
+export type LoadPluginResult = {
+    success: true;
+    plugin: LoadedPlugin;
+} | {
+    success: false;
+    errors: string[];
+};
+/** Reads and validates a plugin from its HTML (e.g. a file uploaded to the Plugin Lab). */
+export declare function loadPluginFromHtml(html: string): LoadPluginResult;
+/** Downloads a plugin HTML file and loads it. */
+export declare function loadPluginFromUrl(url: string, fetchImpl?: typeof fetch): Promise<LoadPluginResult>;
+export interface PreparedSet {
+    /** The items the plugin plays, in display order with answers (the authority; solo). */
+    set: {
+        meta: OQSEMeta;
+        items: OQSEAnyItem[];
+    };
+    /** The same items without answers (other instances in multiplayer, the relay bundle). */
+    publicSet: {
+        meta: OQSEMeta;
+        items: OQSEAnyItem[];
+    };
+    compatibility: CompatibilityReport;
+    /** Items left out because the plugin does not declare their type. */
+    skippedItems: number;
+}
+/**
+ * Keeps only the item types the plugin declares and reports the OQSEM
+ * handshake (`checkCompatibility`). The set should already be loaded with
+ * `loadOQSEFile`. With a `seed` (normally the session id) the options, pairs
+ * and orders are shuffled once for the session (SPEC 4.4).
+ */
+export declare function prepareSetForPlugin(file: OQSEFile, manifest: PluginManifest, options?: {
+    seed?: string;
+}): PreparedSet;
+/**
+ * An empty study set for a plugin that plays without one (`appSpecific.memizy.set` is
+ * `"none"`, or `"optional"` and the host chose no set). The plugin gets `items: []`.
+ */
+export declare function createEmptySet(meta: {
+    title: string;
+    language: string;
+}): OQSEFile;