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

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @memizy/host-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run Memizy plugins in a host application (the Memizy app, the Plugin Lab): load and validate plugins, mount them in sandboxed iframes, enforce the [Memizy Plugin Protocol](../protocol/SPEC.md) and run game sessions.
+
+```ts
+import { loadOQSEFile } from '@memizy/oqse';
+import { loadPluginFromHtml, LocalSession, mountPlugin } from '@memizy/host-sdk';
+
+const loaded = loadPluginFromHtml(html);            // manifest validated without running the plugin
+if (!loaded.success) throw new Error(loaded.errors.join('\n'));
+
+const session = new LocalSession({
+  plugin: loaded.plugin,
+  set: loadOQSEFile(setJson).data!,
+  mode: 'multiplayer',
+  hostAs: 'presenter',
+  players: [{ id: 'anna', name: 'Anna' }, { id: 'ben', name: 'Ben' }],
+});
+session.on((event) => console.log(event));        // ready, countdown, answer, ended, traffic, rejected…
+
+await mountPlugin(session, 'board', boardElement); // sandboxed iframe + Penpal
+await mountPlugin(session, 'anna', annaElement);
+await mountPlugin(session, 'ben', benElement);
+await session.start();                              // waits for everyone, countdown, start
+```
+
+* **`LocalSession`** – all instances in one page (Lab, solo games in the app). Validates every plugin call (schemas, size and rate limits, views, authority), routes messages, runs the start barrier and countdown, handles authority outages (`setConnected`), reloads (`reload`), late joining (`addPlayer`), snapshots, learning progress and plugin data. Multiplayer across devices will use the same API with a relay transport.
+* **`HostStorage`** – plug in your persistence (`MemoryStorage` for the Lab and tests).
+* **`LearningAlgorithm`** – how answers change learning progress (`leitner` by default).
+* **`prepareSetForPlugin` / `checkCompatibility`** – keep only item types the plugin supports, decide which plugins can play a set.
+
+Iframes are sandboxed with `allow-scripts allow-forms allow-modals allow-pointer-lock` and **never** `allow-same-origin`.

package/dist/frame.cjs

@@ -0,0 +1 @@
+let e=require("@memizy/protocol"),t=require("penpal");var n=`allow-scripts allow-forms allow-modals allow-pointer-lock`;function r(t){let n={};for(let r of e.PLUGIN_API_METHODS)n[r]=async(...n)=>{try{return await t[r](...n)}catch(t){throw(0,e.toProtocolError)(t)}};return n}function i(i,a,o,s=document){let c=s.createElement(`iframe`);c.setAttribute(`sandbox`,n),c.setAttribute(`title`,a),c.style.cssText=`width:100%;height:100%;border:0;display:block;touch-action:manipulation;touch-action:pan-x pan-y;`;let l=(0,e.readPluginManifestFromHtml)(i),u=l.success?l.runtime:null,d=(0,e.pluginAllowAttribute)(u);d&&c.setAttribute(`allow`,d);let f=s.defaultView?.location?.origin??null;c.srcdoc=(0,e.injectContentPolicy)(i,(0,e.pluginContentPolicy)(u,f));let p=null;return{iframe:c,plugin:new Promise((n,i)=>{queueMicrotask(()=>{if(!c.contentWindow){i(Error(`The plugin iframe is not in the document.`));return}(0,e.ensureConnectionPolyfills)(),p=(0,t.connect)({messenger:new t.WindowMessenger({remoteWindow:c.contentWindow,allowedOrigins:[`*`]}),methods:o,timeout:e.LIMITS.helloTimeoutMs}),p.promise.then(e=>n(r(e)),i)})}),destroy:()=>p?.destroy()}}async function a(e,t,n,r={}){let a=n.ownerDocument,o=e.config.locale.startsWith(`cs`),s={waitingForHost:r.texts?.waitingForHost??(o?`Čekáme na hostitele…`:`Waiting for the host…`),countdown:r.texts?.countdown??(e=>String(e))},c=a.createElement(`div`);c.className=`mz-host-frame`,c.style.cssText=`position:relative;width:100%;height:100%;`;let l=a.createElement(`div`);l.className=`mz-host-overlay`,l.style.cssText=`position:absolute;inset:0;display:none;place-items:center;background:rgba(0,0,0,.55);color:#fff;font:600 1.5rem system-ui,sans-serif;text-align:center;padding:16px;`;let u=null,d=null;n.appendChild(c);let f=e=>{r.overlays!==!1&&(l.textContent=e??``,l.style.display=e?`grid`:`none`)},p=e.on(n=>{n.type===`countdown`?f(s.countdown(n.secondsLeft)):n.type===`started`?f(null):n.type===`authority`&&t!==e.authority?f(n.connected?null:s.waitingForHost):n.type===`resize`&&n.address===t&&(c.style.height=n.height===`auto`?``:`${n.height}px`)});return{instance:await e.connect(t,async t=>{d?.(),u?.remove();let n=i(e.plugin.html,e.plugin.manifest.appName,t,a);return u=n.iframe,c.replaceChildren(u,l),d=n.destroy,n.plugin},{onDispose:()=>{d?.(),d=null}}),get iframe(){return u},unmount(){p(),e.disconnect(t),c.remove()}}}exports.PLUGIN_SANDBOX=n,exports.createPluginFrame=i,exports.mountPlugin=a;

package/dist/frame.js

@@ -0,0 +1,77 @@
+import { LIMITS as e, PLUGIN_API_METHODS as t, ensureConnectionPolyfills as n, injectContentPolicy as r, pluginAllowAttribute as i, pluginContentPolicy as a, readPluginManifestFromHtml as o, toProtocolError as s } from "@memizy/protocol";
+import { WindowMessenger as c, connect as l } from "penpal";
+//#region src/frame.ts
+var u = "allow-scripts allow-forms allow-modals allow-pointer-lock";
+function d(e) {
+	let n = {};
+	for (let r of t) n[r] = async (...t) => {
+		try {
+			return await e[r](...t);
+		} catch (e) {
+			throw s(e);
+		}
+	};
+	return n;
+}
+function f(t, s, f, p = document) {
+	let m = p.createElement("iframe");
+	m.setAttribute("sandbox", u), m.setAttribute("title", s), m.style.cssText = "width:100%;height:100%;border:0;display:block;touch-action:manipulation;touch-action:pan-x pan-y;";
+	let h = o(t), g = h.success ? h.runtime : null, _ = i(g);
+	_ && m.setAttribute("allow", _);
+	let v = p.defaultView?.location?.origin ?? null;
+	m.srcdoc = r(t, a(g, v));
+	let y = null;
+	return {
+		iframe: m,
+		plugin: new Promise((t, r) => {
+			queueMicrotask(() => {
+				if (!m.contentWindow) {
+					r(/* @__PURE__ */ Error("The plugin iframe is not in the document."));
+					return;
+				}
+				n(), y = l({
+					messenger: new c({
+						remoteWindow: m.contentWindow,
+						allowedOrigins: ["*"]
+					}),
+					methods: f,
+					timeout: e.helloTimeoutMs
+				}), y.promise.then((e) => t(d(e)), r);
+			});
+		}),
+		destroy: () => y?.destroy()
+	};
+}
+async function p(e, t, n, r = {}) {
+	let i = n.ownerDocument, a = e.config.locale.startsWith("cs"), o = {
+		waitingForHost: r.texts?.waitingForHost ?? (a ? "Čekáme na hostitele…" : "Waiting for the host…"),
+		countdown: r.texts?.countdown ?? ((e) => String(e))
+	}, s = i.createElement("div");
+	s.className = "mz-host-frame", s.style.cssText = "position:relative;width:100%;height:100%;";
+	let c = i.createElement("div");
+	c.className = "mz-host-overlay", c.style.cssText = "position:absolute;inset:0;display:none;place-items:center;background:rgba(0,0,0,.55);color:#fff;font:600 1.5rem system-ui,sans-serif;text-align:center;padding:16px;";
+	let l = null, u = null;
+	n.appendChild(s);
+	let d = (e) => {
+		r.overlays !== !1 && (c.textContent = e ?? "", c.style.display = e ? "grid" : "none");
+	}, p = e.on((n) => {
+		n.type === "countdown" ? d(o.countdown(n.secondsLeft)) : n.type === "started" ? d(null) : n.type === "authority" && t !== e.authority ? d(n.connected ? null : o.waitingForHost) : n.type === "resize" && n.address === t && (s.style.height = n.height === "auto" ? "" : `${n.height}px`);
+	});
+	return {
+		instance: await e.connect(t, async (t) => {
+			u?.(), l?.remove();
+			let n = f(e.plugin.html, e.plugin.manifest.appName, t, i);
+			return l = n.iframe, s.replaceChildren(l, c), u = n.destroy, n.plugin;
+		}, { onDispose: () => {
+			u?.(), u = null;
+		} }),
+		get iframe() {
+			return l;
+		},
+		unmount() {
+			p(), e.disconnect(t), s.remove();
+		}
+	};
+}
+//#endregion
+export { u as PLUGIN_SANDBOX, f as createPluginFrame, p as mountPlugin };

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./plugin.cjs"),t=require("./learning.cjs"),n=require("./storage.cjs"),r=require("./session.cjs"),i=require("./frame.cjs"),a=require("./relay/socket.cjs"),o=require("./relay/messages.cjs"),s=require("./relay/host.cjs"),c=require("./relay/player.cjs");exports.LEITNER_INTERVAL_DAYS=t.LEITNER_INTERVAL_DAYS,exports.LocalSession=r.LocalSession,exports.MemoryStorage=n.MemoryStorage,exports.PLUGIN_SANDBOX=i.PLUGIN_SANDBOX,exports.RelayHost=s.RelayHost,exports.RelayPlayer=c.RelayPlayer,exports.RelaySocket=a.RelaySocket,exports.SETTINGS_ADDRESS=r.SETTINGS_ADDRESS,exports.blobToJson=o.blobToJson,exports.createEmptySet=e.createEmptySet,exports.createPluginFrame=i.createPluginFrame,exports.isSerializedBlob=o.isSerializedBlob,exports.jsonToBlob=o.jsonToBlob,exports.leitner=t.leitner,exports.loadPluginFromHtml=e.loadPluginFromHtml,exports.loadPluginFromUrl=e.loadPluginFromUrl,exports.mountPlugin=i.mountPlugin,exports.prepareSetForPlugin=e.prepareSetForPlugin,exports.relayWebSocketUrl=a.relayWebSocketUrl,exports.serializeError=o.serializeError;

package/dist/index.js

@@ -0,0 +1,10 @@
+import { createEmptySet as e, loadPluginFromHtml as t, loadPluginFromUrl as n, prepareSetForPlugin as r } from "./plugin.js";
+import { LEITNER_INTERVAL_DAYS as i, leitner as a } from "./learning.js";
+import { MemoryStorage as o } from "./storage.js";
+import { LocalSession as s, SETTINGS_ADDRESS as c } from "./session.js";
+import { PLUGIN_SANDBOX as l, createPluginFrame as u, mountPlugin as d } from "./frame.js";
+import { RelaySocket as f, relayWebSocketUrl as p } from "./relay/socket.js";
+import { blobToJson as m, isSerializedBlob as h, jsonToBlob as g, serializeError as _ } from "./relay/messages.js";
+import { RelayHost as v } from "./relay/host.js";
+import { RelayPlayer as y } from "./relay/player.js";
+export { i as LEITNER_INTERVAL_DAYS, s as LocalSession, o as MemoryStorage, l as PLUGIN_SANDBOX, v as RelayHost, y as RelayPlayer, f as RelaySocket, c as SETTINGS_ADDRESS, m as blobToJson, e as createEmptySet, u as createPluginFrame, h as isSerializedBlob, g as jsonToBlob, a as leitner, t as loadPluginFromHtml, n as loadPluginFromUrl, d as mountPlugin, r as prepareSetForPlugin, p as relayWebSocketUrl, _ as serializeError };

package/dist/learning.cjs

@@ -0,0 +1 @@
+var e=[0,1,3,7,21],t={id:`leitner`,apply(t,n,r){let i=t?.stats??{attempts:0,incorrect:0,streak:0},a={isCorrect:!n.isSkipped&&n.isCorrect,answeredAt:r.toISOString(),...n.confidence!==void 0&&{confidence:n.confidence},...n.timeSpentMs!==void 0&&{timeSpent:n.timeSpentMs},...n.hintsUsed!==void 0&&{hintsUsed:n.hintsUsed},...n.isSkipped&&{isSkipped:!0}};if(n.isSkipped)return{...t??{bucket:0},stats:i,lastAnswer:a};let o=n.isCorrect?Math.min(4,Math.max(1,t?.bucket??0)+1):1,s=new Date(r.getTime()+e[o]*24*60*60*1e3);return{...t,bucket:o,nextReviewAt:s.toISOString(),stats:{attempts:i.attempts+1,incorrect:i.incorrect+ +!n.isCorrect,streak:n.isCorrect?i.streak+1:0},lastAnswer:a}}};exports.LEITNER_INTERVAL_DAYS=e,exports.leitner=t;

package/dist/learning.js

@@ -0,0 +1,43 @@
+//#region src/learning.ts
+var e = [
+	0,
+	1,
+	3,
+	7,
+	21
+], t = {
+	id: "leitner",
+	apply(t, n, r) {
+		let i = t?.stats ?? {
+			attempts: 0,
+			incorrect: 0,
+			streak: 0
+		}, a = {
+			isCorrect: !n.isSkipped && n.isCorrect,
+			answeredAt: r.toISOString(),
+			...n.confidence !== void 0 && { confidence: n.confidence },
+			...n.timeSpentMs !== void 0 && { timeSpent: n.timeSpentMs },
+			...n.hintsUsed !== void 0 && { hintsUsed: n.hintsUsed },
+			...n.isSkipped && { isSkipped: !0 }
+		};
+		if (n.isSkipped) return {
+			...t ?? { bucket: 0 },
+			stats: i,
+			lastAnswer: a
+		};
+		let o = n.isCorrect ? Math.min(4, Math.max(1, t?.bucket ?? 0) + 1) : 1, s = new Date(r.getTime() + e[o] * 24 * 60 * 60 * 1e3);
+		return {
+			...t,
+			bucket: o,
+			nextReviewAt: s.toISOString(),
+			stats: {
+				attempts: i.attempts + 1,
+				incorrect: i.incorrect + +!n.isCorrect,
+				streak: n.isCorrect ? i.streak + 1 : 0
+			},
+			lastAnswer: a
+		};
+	}
+};
+//#endregion
+export { e as LEITNER_INTERVAL_DAYS, t as leitner };

package/dist/plugin.cjs

@@ -0,0 +1 @@
+let e=require("@memizy/protocol"),t=require("@memizy/oqse");function n(t){let n=(0,e.readPluginManifestFromHtml)(t);return n.success?(0,e.isProtocolSupported)(n.runtime.protocol)?{success:!0,plugin:{html:t,manifest:n.manifest,runtime:n.runtime}}:{success:!1,errors:[`The plugin needs Memizy Plugin Protocol ${n.runtime.protocol}, which this host does not support.`]}:n}async function r(e,t=fetch){let r=await t(e);return r.ok?n(await r.text()):{success:!1,errors:[`Could not download the plugin (${r.status} ${r.statusText}).`]}}function i(n,r,i={}){let a=r.capabilities?.types??[],o=a.includes(`*`)?n.items:n.items.filter(e=>a.includes(e.type)),s=(0,e.prepareDisplaySet)({meta:n.meta,items:o},i.seed);return{set:s.set,publicSet:s.publicSet,compatibility:(0,t.checkCompatibility)(n,r),skippedItems:n.items.length-o.length}}function a(e){let n=new Date().toISOString();return{version:t.OQSE_VERSION,meta:{id:(0,t.generateUUID)(),title:e.title,language:e.language,createdAt:n,updatedAt:n},items:[]}}exports.createEmptySet=a,exports.loadPluginFromHtml=n,exports.loadPluginFromUrl=r,exports.prepareSetForPlugin=i;

package/dist/plugin.js

@@ -0,0 +1,52 @@
+import { isProtocolSupported as e, prepareDisplaySet as t, readPluginManifestFromHtml as n } from "@memizy/protocol";
+import { OQSE_VERSION as r, checkCompatibility as i, generateUUID as a } from "@memizy/oqse";
+//#region src/plugin.ts
+function o(t) {
+	let r = n(t);
+	return r.success ? e(r.runtime.protocol) ? {
+		success: !0,
+		plugin: {
+			html: t,
+			manifest: r.manifest,
+			runtime: r.runtime
+		}
+	} : {
+		success: !1,
+		errors: [`The plugin needs Memizy Plugin Protocol ${r.runtime.protocol}, which this host does not support.`]
+	} : r;
+}
+async function s(e, t = fetch) {
+	let n = await t(e);
+	return n.ok ? o(await n.text()) : {
+		success: !1,
+		errors: [`Could not download the plugin (${n.status} ${n.statusText}).`]
+	};
+}
+function c(e, n, r = {}) {
+	let a = n.capabilities?.types ?? [], o = a.includes("*") ? e.items : e.items.filter((e) => a.includes(e.type)), s = t({
+		meta: e.meta,
+		items: o
+	}, r.seed);
+	return {
+		set: s.set,
+		publicSet: s.publicSet,
+		compatibility: i(e, n),
+		skippedItems: e.items.length - o.length
+	};
+}
+function l(e) {
+	let t = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		version: r,
+		meta: {
+			id: a(),
+			title: e.title,
+			language: e.language,
+			createdAt: t,
+			updatedAt: t
+		},
+		items: []
+	};
+}
+//#endregion
+export { l as createEmptySet, o as loadPluginFromHtml, s as loadPluginFromUrl, c as prepareSetForPlugin };

package/dist/relay/host.cjs

@@ -0,0 +1 @@
+const e=require("./socket.cjs"),t=require("./messages.cjs");let n=require("@memizy/protocol");var r=new Set(n.HOST_API_METHODS),i=class i{pin;hostToken;players=[];state={phase:`lobby`,appName:null,players:[],authorityConnected:!0};options;socket;listeners=new Set;channels=new Map;bundleVersion=0;genCounter=0;callCounter=0;session=null;hosting=!1;hostingWaiters=[];stopSession=null;constructor(t,r){this.options=t,this.pin=r.pin,this.hostToken=r.hostToken,this.socket=new e.RelaySocket({url:e.relayWebSocketUrl(t.serverUrl),attach:()=>({t:`host`,protocol:n.RELAY_PROTOCOL,pin:this.pin,hostToken:this.hostToken}),WebSocket:t.WebSocket}),this.socket.onStatus(e=>this.emit({type:`status`,status:e})),this.socket.onMessage(e=>this.onServer(e))}static async create(e){let t=await(e.fetch??fetch)(new URL(`/api/rooms`,e.serverUrl),{method:`POST`});if(!t.ok)throw Error(`Could not create a room (${t.status}): ${await t.text()}`);return new i(e,await t.json())}static resume(e,t){return new i(e,t)}whenHosting(){return this.hosting?Promise.resolve():new Promise(e=>this.hostingWaiters.push(e))}get status(){return this.socket.status}on(e){return this.listeners.add(e),()=>this.listeners.delete(e)}emit(e){for(let t of this.listeners)t(e)}async uploadBundle(e,t){let n=await(this.options.fetch??fetch)(new URL(`/api/rooms/${this.pin}/bundle`,this.options.serverUrl),{method:`PUT`,headers:{Authorization:`Bearer ${this.hostToken}`,"Content-Type":`application/json`},body:JSON.stringify({pluginHtml:e,set:t})});if(!n.ok)throw Error(`Could not upload the game (${n.status}): ${await n.text()}`);return this.bundleVersion=(await n.json()).version,this.bundleVersion}setOpen(e){this.socket.send({t:`open`,open:e})}kick(e){this.socket.send({t:`kick`,playerId:e})}close(){this.detach(),this.socket.send({t:`close`}),this.socket.close()}disconnect(){this.detach(),this.socket.close()}setState(e){this.state={...this.state,...e},this.broadcast({k:`state`,state:this.state})}attach(e){this.detach(),this.session=e;let t=new Set(this.players.map(e=>e.id));for(let t of this.players)!t.connected&&e.players.some(e=>e.id===t.id)&&e.setConnected(t.id,!1);for(let n of e.players)t.has(n.id)&&this.connectRemote(n.id);this.stopSession=e.on(e=>this.onSessionEvent(e)),this.setState({phase:`loading`,appName:e.plugin.manifest.appName,players:e.players,authorityConnected:!0,result:void 0,countdown:void 0})}detach(){this.stopSession?.(),this.stopSession=null,this.session=null;for(let[e,t]of this.channels)this.resetChannel(e,t);this.broadcast({k:`unmount`})}onSessionEvent(e){switch(e.type){case`countdown`:this.setState({phase:`countdown`,countdown:e.secondsLeft});break;case`started`:this.setState({phase:`running`,countdown:void 0});break;case`players`:this.setState({players:e.players});break;case`authority`:this.setState({authorityConnected:e.connected});break;case`ended`:this.setState({phase:`ended`,result:e.result})}}connectRemote(e){let t=this.session;t&&t.connect(e,this.endpointFor(e)).catch(()=>{})}endpointFor(e){return t=>new Promise((n,r)=>{let i=this.channel(e);this.resetChannel(e,i);let a=++this.genCounter;i.gen=a,i.hostApi=t,i.pendingMount={gen:a,resolve:()=>n(this.remotePlugin(e,a)),reject:r,timer:setTimeout(()=>{i.pendingMount?.gen===a&&(i.pendingMount=null,r(Error(`The device of player ${e} did not load the game in time.`)))},this.options.mountTimeoutMs??2e4)},this.sendMount(e,a)})}sendMount(e,t){this.sendTo(e,{k:`mount`,gen:t,bundle:this.bundleVersion,locale:this.session?.config.locale??`cs`})}remotePlugin(e,t){let r={};for(let i of n.PLUGIN_API_METHODS)r[i]=(...n)=>this.callRemote(e,t,i,n);return r}callRemote(e,t,n,r){let i=this.channels.get(e);if(!i||i.gen!==t)return Promise.reject(Error(`[SESSION_ENDED] The player instance was replaced.`));if(!this.players.find(t=>t.id===e)?.connected)return Promise.resolve();let a=++this.callCounter;return new Promise((o,s)=>{let c=setTimeout(()=>{i.calls.delete(a),s(Error(`[INTERNAL_ERROR] ${n} on ${e} timed out.`))},this.options.callTimeoutMs??15e3);i.calls.set(a,{resolve:o,reject:s,timer:c}),this.sendTo(e,{k:`call`,id:a,gen:t,method:n,args:r})})}channel(e){let t=this.channels.get(e);return t||(t={gen:0,hostApi:null,pendingMount:null,calls:new Map},this.channels.set(e,t)),t}resetChannel(e,t){t.pendingMount&&=(clearTimeout(t.pendingMount.timer),t.pendingMount.reject(Error(`[SESSION_ENDED] Replaced.`)),null),this.settleCalls(t),t.gen=0,t.hostApi=null}settleCalls(e){for(let t of e.calls.values())clearTimeout(t.timer),t.resolve(void 0);e.calls.clear()}onServer(e){switch(e.t){case`hosting`:this.hosting=!0,this.hostingWaiters.splice(0).forEach(e=>e()),this.players=e.players,this.emit({type:`players`,players:this.players}),this.broadcast({k:`state`,state:this.state});break;case`presence`:this.onPresence(e.player,e.event);break;case`from`:this.onPlayer(e.from,e.data);break;case`error`:this.emit({type:`error`,code:e.code,message:e.message});break;case`closed`:this.emit({type:`closed`,reason:e.reason})}}onPresence(e,t){this.players=t===`leave`?this.players.filter(t=>t.id!==e.id):this.players.some(t=>t.id===e.id)?this.players.map(t=>t.id===e.id?e:t):[...this.players,e],this.emit({type:`players`,players:this.players});let n=this.session,r=n?.players.some(t=>t.id===e.id)??!1;switch(t){case`join`:if(n&&!n.ended&&!r)try{n.addPlayer({id:e.id,name:e.name}),this.connectRemote(e.id)}catch{}break;case`disconnect`:{let t=this.channels.get(e.id);t&&this.settleCalls(t),r&&n.setConnected(e.id,!1);break}case`rename`:r&&n.renamePlayer(e.id,e.name);break;case`leave`:if(this.channels.delete(e.id),r)try{n.removePlayer(e.id)}catch{}}}async onPlayer(e,n){if(typeof n!=`object`||!n)return;let i=this.channel(e);switch(n.k){case`hello`:{this.sendTo(e,{k:`state`,state:this.state});let t=this.session;if(!t||!t.players.some(t=>t.id===e))return;if(i.pendingMount){this.sendMount(e,i.pendingMount.gen);return}t.setConnected(e,!0),(i.gen===0||n.gen!==i.gen)&&(t.getInstance(e)?t.reload(e).catch(()=>{}):this.connectRemote(e));return}case`mounted`:if(i.pendingMount?.gen===n.gen){clearTimeout(i.pendingMount.timer);let e=i.pendingMount;i.pendingMount=null,e.resolve()}return;case`mount-failed`:if(i.pendingMount?.gen===n.gen){clearTimeout(i.pendingMount.timer);let e=i.pendingMount;i.pendingMount=null,e.reject(Error(n.error?.message??`The game could not be loaded on the device.`))}return;case`result`:{let e=i.calls.get(n.id);if(!e)return;i.calls.delete(n.id),clearTimeout(e.timer),n.ok?e.resolve(n.value):e.reject(Error(n.error?.message??`Remote call failed`));return}case`call`:{let a=t=>this.sendTo(e,t);if(n.gen!==i.gen||!i.hostApi||!r.has(n.method)||!Array.isArray(n.args)){a({k:`result`,id:n.id,ok:!1,error:{message:`[SESSION_ENDED] This plugin instance is no longer active.`}});return}try{let e=i.hostApi[n.method],r=await e(...n.args);if(n.method===`hello`){r={...r,set:null},a({k:`result`,id:n.id,ok:!0,value:r,hostNow:Date.now()});return}n.method===`getAsset`&&r instanceof Blob&&(r=await t.blobToJson(r)),a({k:`result`,id:n.id,ok:!0,value:r??null})}catch(e){a({k:`result`,id:n.id,ok:!1,error:t.serializeError(e)})}return}}}sendTo(e,t){this.socket.send({t:`to`,to:e,data:t})}broadcast(e){for(let t of this.players)t.connected&&this.sendTo(t.id,e)}};exports.RelayHost=i;

package/dist/relay/host.js

@@ -0,0 +1,370 @@
+import { RelaySocket as e, relayWebSocketUrl as t } from "./socket.js";
+import { blobToJson as n, serializeError as r } from "./messages.js";
+import { HOST_API_METHODS as i, PLUGIN_API_METHODS as a, RELAY_PROTOCOL as o } from "@memizy/protocol";
+//#region src/relay/host.ts
+var s = new Set(i), c = class i {
+	pin;
+	hostToken;
+	players = [];
+	state = {
+		phase: "lobby",
+		appName: null,
+		players: [],
+		authorityConnected: !0
+	};
+	options;
+	socket;
+	listeners = /* @__PURE__ */ new Set();
+	channels = /* @__PURE__ */ new Map();
+	bundleVersion = 0;
+	genCounter = 0;
+	callCounter = 0;
+	session = null;
+	hosting = !1;
+	hostingWaiters = [];
+	stopSession = null;
+	constructor(n, r) {
+		this.options = n, this.pin = r.pin, this.hostToken = r.hostToken, this.socket = new e({
+			url: t(n.serverUrl),
+			attach: () => ({
+				t: "host",
+				protocol: o,
+				pin: this.pin,
+				hostToken: this.hostToken
+			}),
+			WebSocket: n.WebSocket
+		}), this.socket.onStatus((e) => this.emit({
+			type: "status",
+			status: e
+		})), this.socket.onMessage((e) => this.onServer(e));
+	}
+	static async create(e) {
+		let t = await (e.fetch ?? fetch)(new URL("/api/rooms", e.serverUrl), { method: "POST" });
+		if (!t.ok) throw Error(`Could not create a room (${t.status}): ${await t.text()}`);
+		return new i(e, await t.json());
+	}
+	static resume(e, t) {
+		return new i(e, t);
+	}
+	whenHosting() {
+		return this.hosting ? Promise.resolve() : new Promise((e) => this.hostingWaiters.push(e));
+	}
+	get status() {
+		return this.socket.status;
+	}
+	on(e) {
+		return this.listeners.add(e), () => this.listeners.delete(e);
+	}
+	emit(e) {
+		for (let t of this.listeners) t(e);
+	}
+	async uploadBundle(e, t) {
+		let n = await (this.options.fetch ?? fetch)(new URL(`/api/rooms/${this.pin}/bundle`, this.options.serverUrl), {
+			method: "PUT",
+			headers: {
+				Authorization: `Bearer ${this.hostToken}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				pluginHtml: e,
+				set: t
+			})
+		});
+		if (!n.ok) throw Error(`Could not upload the game (${n.status}): ${await n.text()}`);
+		return this.bundleVersion = (await n.json()).version, this.bundleVersion;
+	}
+	setOpen(e) {
+		this.socket.send({
+			t: "open",
+			open: e
+		});
+	}
+	kick(e) {
+		this.socket.send({
+			t: "kick",
+			playerId: e
+		});
+	}
+	close() {
+		this.detach(), this.socket.send({ t: "close" }), this.socket.close();
+	}
+	disconnect() {
+		this.detach(), this.socket.close();
+	}
+	setState(e) {
+		this.state = {
+			...this.state,
+			...e
+		}, this.broadcast({
+			k: "state",
+			state: this.state
+		});
+	}
+	attach(e) {
+		this.detach(), this.session = e;
+		let t = new Set(this.players.map((e) => e.id));
+		for (let t of this.players) !t.connected && e.players.some((e) => e.id === t.id) && e.setConnected(t.id, !1);
+		for (let n of e.players) t.has(n.id) && this.connectRemote(n.id);
+		this.stopSession = e.on((e) => this.onSessionEvent(e)), this.setState({
+			phase: "loading",
+			appName: e.plugin.manifest.appName,
+			players: e.players,
+			authorityConnected: !0,
+			result: void 0,
+			countdown: void 0
+		});
+	}
+	detach() {
+		this.stopSession?.(), this.stopSession = null, this.session = null;
+		for (let [e, t] of this.channels) this.resetChannel(e, t);
+		this.broadcast({ k: "unmount" });
+	}
+	onSessionEvent(e) {
+		switch (e.type) {
+			case "countdown":
+				this.setState({
+					phase: "countdown",
+					countdown: e.secondsLeft
+				});
+				break;
+			case "started":
+				this.setState({
+					phase: "running",
+					countdown: void 0
+				});
+				break;
+			case "players":
+				this.setState({ players: e.players });
+				break;
+			case "authority":
+				this.setState({ authorityConnected: e.connected });
+				break;
+			case "ended": this.setState({
+				phase: "ended",
+				result: e.result
+			});
+		}
+	}
+	connectRemote(e) {
+		let t = this.session;
+		t && t.connect(e, this.endpointFor(e)).catch(() => {});
+	}
+	endpointFor(e) {
+		return (t) => new Promise((n, r) => {
+			let i = this.channel(e);
+			this.resetChannel(e, i);
+			let a = ++this.genCounter;
+			i.gen = a, i.hostApi = t, i.pendingMount = {
+				gen: a,
+				resolve: () => n(this.remotePlugin(e, a)),
+				reject: r,
+				timer: setTimeout(() => {
+					i.pendingMount?.gen === a && (i.pendingMount = null, r(/* @__PURE__ */ Error(`The device of player ${e} did not load the game in time.`)));
+				}, this.options.mountTimeoutMs ?? 2e4)
+			}, this.sendMount(e, a);
+		});
+	}
+	sendMount(e, t) {
+		this.sendTo(e, {
+			k: "mount",
+			gen: t,
+			bundle: this.bundleVersion,
+			locale: this.session?.config.locale ?? "cs"
+		});
+	}
+	remotePlugin(e, t) {
+		let n = {};
+		for (let r of a) n[r] = (...n) => this.callRemote(e, t, r, n);
+		return n;
+	}
+	callRemote(e, t, n, r) {
+		let i = this.channels.get(e);
+		if (!i || i.gen !== t) return Promise.reject(/* @__PURE__ */ Error("[SESSION_ENDED] The player instance was replaced."));
+		if (!this.players.find((t) => t.id === e)?.connected) return Promise.resolve();
+		let a = ++this.callCounter;
+		return new Promise((o, s) => {
+			let c = setTimeout(() => {
+				i.calls.delete(a), s(/* @__PURE__ */ Error(`[INTERNAL_ERROR] ${n} on ${e} timed out.`));
+			}, this.options.callTimeoutMs ?? 15e3);
+			i.calls.set(a, {
+				resolve: o,
+				reject: s,
+				timer: c
+			}), this.sendTo(e, {
+				k: "call",
+				id: a,
+				gen: t,
+				method: n,
+				args: r
+			});
+		});
+	}
+	channel(e) {
+		let t = this.channels.get(e);
+		return t || (t = {
+			gen: 0,
+			hostApi: null,
+			pendingMount: null,
+			calls: /* @__PURE__ */ new Map()
+		}, this.channels.set(e, t)), t;
+	}
+	resetChannel(e, t) {
+		t.pendingMount &&= (clearTimeout(t.pendingMount.timer), t.pendingMount.reject(/* @__PURE__ */ Error("[SESSION_ENDED] Replaced.")), null), this.settleCalls(t), t.gen = 0, t.hostApi = null;
+	}
+	settleCalls(e) {
+		for (let t of e.calls.values()) clearTimeout(t.timer), t.resolve(void 0);
+		e.calls.clear();
+	}
+	onServer(e) {
+		switch (e.t) {
+			case "hosting":
+				this.hosting = !0, this.hostingWaiters.splice(0).forEach((e) => e()), this.players = e.players, this.emit({
+					type: "players",
+					players: this.players
+				}), this.broadcast({
+					k: "state",
+					state: this.state
+				});
+				break;
+			case "presence":
+				this.onPresence(e.player, e.event);
+				break;
+			case "from":
+				this.onPlayer(e.from, e.data);
+				break;
+			case "error":
+				this.emit({
+					type: "error",
+					code: e.code,
+					message: e.message
+				});
+				break;
+			case "closed": this.emit({
+				type: "closed",
+				reason: e.reason
+			});
+		}
+	}
+	onPresence(e, t) {
+		this.players = t === "leave" ? this.players.filter((t) => t.id !== e.id) : this.players.some((t) => t.id === e.id) ? this.players.map((t) => t.id === e.id ? e : t) : [...this.players, e], this.emit({
+			type: "players",
+			players: this.players
+		});
+		let n = this.session, r = n?.players.some((t) => t.id === e.id) ?? !1;
+		switch (t) {
+			case "join":
+				if (n && !n.ended && !r) try {
+					n.addPlayer({
+						id: e.id,
+						name: e.name
+					}), this.connectRemote(e.id);
+				} catch {}
+				break;
+			case "disconnect": {
+				let t = this.channels.get(e.id);
+				t && this.settleCalls(t), r && n.setConnected(e.id, !1);
+				break;
+			}
+			case "rename":
+				r && n.renamePlayer(e.id, e.name);
+				break;
+			case "leave": if (this.channels.delete(e.id), r) try {
+				n.removePlayer(e.id);
+			} catch {}
+		}
+	}
+	async onPlayer(e, t) {
+		if (typeof t != "object" || !t) return;
+		let i = this.channel(e);
+		switch (t.k) {
+			case "hello": {
+				this.sendTo(e, {
+					k: "state",
+					state: this.state
+				});
+				let n = this.session;
+				if (!n || !n.players.some((t) => t.id === e)) return;
+				if (i.pendingMount) {
+					this.sendMount(e, i.pendingMount.gen);
+					return;
+				}
+				n.setConnected(e, !0), (i.gen === 0 || t.gen !== i.gen) && (n.getInstance(e) ? n.reload(e).catch(() => {}) : this.connectRemote(e));
+				return;
+			}
+			case "mounted":
+				if (i.pendingMount?.gen === t.gen) {
+					clearTimeout(i.pendingMount.timer);
+					let e = i.pendingMount;
+					i.pendingMount = null, e.resolve();
+				}
+				return;
+			case "mount-failed":
+				if (i.pendingMount?.gen === t.gen) {
+					clearTimeout(i.pendingMount.timer);
+					let e = i.pendingMount;
+					i.pendingMount = null, e.reject(Error(t.error?.message ?? "The game could not be loaded on the device."));
+				}
+				return;
+			case "result": {
+				let e = i.calls.get(t.id);
+				if (!e) return;
+				i.calls.delete(t.id), clearTimeout(e.timer), t.ok ? e.resolve(t.value) : e.reject(Error(t.error?.message ?? "Remote call failed"));
+				return;
+			}
+			case "call": {
+				let a = (t) => this.sendTo(e, t);
+				if (t.gen !== i.gen || !i.hostApi || !s.has(t.method) || !Array.isArray(t.args)) {
+					a({
+						k: "result",
+						id: t.id,
+						ok: !1,
+						error: { message: "[SESSION_ENDED] This plugin instance is no longer active." }
+					});
+					return;
+				}
+				try {
+					let e = i.hostApi[t.method], r = await e(...t.args);
+					if (t.method === "hello") {
+						r = {
+							...r,
+							set: null
+						}, a({
+							k: "result",
+							id: t.id,
+							ok: !0,
+							value: r,
+							hostNow: Date.now()
+						});
+						return;
+					}
+					t.method === "getAsset" && r instanceof Blob && (r = await n(r)), a({
+						k: "result",
+						id: t.id,
+						ok: !0,
+						value: r ?? null
+					});
+				} catch (e) {
+					a({
+						k: "result",
+						id: t.id,
+						ok: !1,
+						error: r(e)
+					});
+				}
+				return;
+			}
+		}
+	}
+	sendTo(e, t) {
+		this.socket.send({
+			t: "to",
+			to: e,
+			data: t
+		});
+	}
+	broadcast(e) {
+		for (let t of this.players) t.connected && this.sendTo(t.id, e);
+	}
+};
+//#endregion
+export { c as RelayHost };

package/dist/relay/messages.cjs

@@ -0,0 +1 @@
+function e(e){return{message:e instanceof Error?e.message:String(e)}}async function t(e){let t=new Uint8Array(await e.arrayBuffer()),n=``;for(let e=0;e<t.length;e+=32768)n+=String.fromCharCode(...t.subarray(e,e+32768));return{$blob:btoa(n),type:e.type}}function n(e){let t=atob(e.$blob),n=new Uint8Array(t.length);for(let e=0;e<t.length;e++)n[e]=t.charCodeAt(e);return new Blob([n],{type:e.type})}function r(e){return typeof e==`object`&&!!e&&typeof e.$blob==`string`}exports.blobToJson=t,exports.isSerializedBlob=r,exports.jsonToBlob=n,exports.serializeError=e;

package/dist/relay/messages.js

@@ -0,0 +1,22 @@
+//#region src/relay/messages.ts
+function e(e) {
+	return { message: e instanceof Error ? e.message : String(e) };
+}
+async function t(e) {
+	let t = new Uint8Array(await e.arrayBuffer()), n = "";
+	for (let e = 0; e < t.length; e += 32768) n += String.fromCharCode(...t.subarray(e, e + 32768));
+	return {
+		$blob: btoa(n),
+		type: e.type
+	};
+}
+function n(e) {
+	let t = atob(e.$blob), n = new Uint8Array(t.length);
+	for (let e = 0; e < t.length; e++) n[e] = t.charCodeAt(e);
+	return new Blob([n], { type: e.type });
+}
+function r(e) {
+	return typeof e == "object" && !!e && typeof e.$blob == "string";
+}
+//#endregion
+export { t as blobToJson, r as isSerializedBlob, n as jsonToBlob, e as serializeError };

package/dist/relay/player.cjs

@@ -0,0 +1 @@
+const e=require("../frame.cjs"),t=require("./socket.cjs"),n=require("./messages.cjs");let r=require("@memizy/protocol");var i=new Set(r.PLUGIN_API_METHODS),a=class{playerId=null;token;name;state=null;hostConnected=!0;options;socket;listeners=new Set;bundle=null;frame=null;plugin=null;gen=0;callCounter=0;pending=new Map;skewMs=0;hostConfig=null;mountQueue=Promise.resolve();constructor(e){this.options=e,this.token=e.token??null,this.name=e.name,this.socket=new t.RelaySocket({url:t.relayWebSocketUrl(e.serverUrl),attach:()=>({t:`join`,protocol:r.RELAY_PROTOCOL,pin:e.pin,name:this.name,token:this.token??void 0}),WebSocket:e.WebSocket}),this.socket.onStatus(e=>this.emit({type:`status`,status:e})),this.socket.onMessage(e=>this.onServer(e))}get status(){return this.socket.status}on(e){return this.listeners.add(e),()=>this.listeners.delete(e)}emit(e){for(let t of this.listeners)t(e)}updateConfig(){this.plugin&&this.hostConfig&&this.plugin.configChanged(this.localConfig(this.hostConfig)).catch(()=>{})}localConfig(e){return{...e,...this.options.config?.()}}rename(e){this.name=e,this.socket.send({t:`rename`,name:e})}reconnectNow(){this.socket.reconnectNow()}leave(){this.destroyFrame(),this.socket.close()}onServer(e){switch(e.t){case`joined`:this.playerId=e.playerId,this.token=e.token,this.name=e.name,this.hostConnected=e.hostConnected,this.emit({type:`joined`,playerId:e.playerId,token:e.token,name:e.name}),this.up({k:`hello`,gen:this.plugin?this.gen:0});break;case`host-presence`:this.hostConnected=e.connected,this.emit({type:`host`,connected:e.connected}),e.connected&&this.up({k:`hello`,gen:this.plugin?this.gen:0});break;case`data`:this.onHost(e.data);break;case`error`:this.emit({type:`error`,code:e.code,message:e.message,fatal:e.fatal});break;case`closed`:this.destroyFrame(),this.emit({type:`closed`,reason:e.reason})}}up(e){return this.socket.send({t:`up`,data:e})}async onHost(e){if(typeof e==`object`&&e)switch(e.k){case`state`:this.state=e.state,this.emit({type:`state`,state:e.state});return;case`mount`:this.mountQueue=this.mountQueue.then(()=>this.mount(e.gen,e.bundle));return;case`unmount`:this.destroyFrame();return;case`result`:{let t=this.pending.get(e.id);if(!t)return;if(this.pending.delete(e.id),clearTimeout(t.timer),!e.ok){t.reject(Error(e.error?.message??`Host call failed`));return}let r=e.value;if(t.method===`hello`&&this.bundle){if(e.hostNow!==void 0){let n=Date.now();this.skewMs=e.hostNow+(n-t.sentAt)/2-n}let n=r;this.hostConfig=n.config,r={...n,set:structuredClone(this.bundle.data.set),clock:{...n.clock,offsetMs:n.clock.offsetMs+this.skewMs},config:this.localConfig(n.config)}}else n.isSerializedBlob(r)&&(r=n.jsonToBlob(r));t.resolve(r);return}case`call`:{let t=e=>this.up(e);if(e.gen!==this.gen||!this.plugin||!i.has(e.method)){t({k:`result`,id:e.id,ok:!1,error:{message:`[SESSION_ENDED] No active plugin instance.`}});return}let r=e.args;if(e.method===`configChanged`&&(this.hostConfig=r[0],r=[this.localConfig(this.hostConfig)]),e.method===`clockChanged`){let e=r[0];r=[{...e,offsetMs:e.offsetMs+this.skewMs}]}try{let n=this.plugin[e.method],i=await n(...r);t({k:`result`,id:e.id,ok:!0,value:i??null})}catch(r){t({k:`result`,id:e.id,ok:!1,error:n.serializeError(r)})}return}}}async ensureBundle(e){if(this.bundle?.version===e)return this.bundle.data;let t=await(this.options.fetch??fetch)(new URL(`/api/rooms/${this.options.pin}/bundle`,this.options.serverUrl));if(!t.ok)throw Error(`Could not download the game (${t.status}).`);let n=await t.json();return this.bundle={version:Number(t.headers.get(`X-Bundle-Version`)??e),data:n},n}async mount(t,i){this.destroyFrame(),this.gen=t;try{let n=await this.ensureBundle(i);if(this.gen!==t)return;let a=this.options.container();if(!a)throw Error(`No place for the game on this page.`);let o=(0,r.extractManifestFromHtml)(n.pluginHtml),s=o.success?String(o.data.appName??`Game`):`Game`,c=this.options.transformHtml?this.options.transformHtml(n.pluginHtml):n.pluginHtml,l=(this.options.createFrame??e.createPluginFrame)(c,s,this.hostApiFor(t),a.ownerDocument);this.frame=l,a.replaceChildren(l.iframe),this.emit({type:`frame`,active:!0});let u=await l.plugin;if(this.gen!==t)return;this.plugin=u,this.up({k:`mounted`,gen:t})}catch(e){if(this.gen!==t)return;this.emit({type:`error`,code:`MOUNT_FAILED`,message:e.message,fatal:!1}),this.up({k:`mount-failed`,gen:t,error:n.serializeError(e)})}}hostApiFor(e){let t={};for(let n of r.HOST_API_METHODS)t[n]=(...t)=>{if(this.gen!==e)return Promise.reject(Error(`[SESSION_ENDED] This plugin instance was replaced.`));let r=++this.callCounter;return new Promise((i,a)=>{let o=setTimeout(()=>{this.pending.delete(r),a(Error(`[INTERNAL_ERROR] The host did not answer ${n} in time.`))},this.options.callTimeoutMs??15e3);this.pending.set(r,{method:n,sentAt:Date.now(),resolve:i,reject:a,timer:o}),this.up({k:`call`,id:r,gen:e,method:n,args:t})||(clearTimeout(o),this.pending.delete(r),n===`hello`?a(Error(`[INTERNAL_ERROR] Offline.`)):i(void 0))})};return t}destroyFrame(){let e=this.frame!==null;this.frame?.destroy(),this.frame?.iframe.remove(),this.frame=null,this.plugin=null,this.gen=0;for(let e of this.pending.values())clearTimeout(e.timer),e.reject(Error(`[SESSION_ENDED] The plugin instance was closed.`));this.pending.clear(),e&&this.emit({type:`frame`,active:!1})}};exports.RelayPlayer=a;